1\documentclass[11pt]{article} 2\input{html.sty} 3\htmladdtonavigation 4 {\begin{rawhtml} 5 <A HREF="http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html">FITSIO Home</A> 6 \end{rawhtml}} 7 8\oddsidemargin=0.20in 9\evensidemargin=0.20in 10\textwidth=15.5truecm 11\textheight=21.5truecm 12 13\title{CFITSIO Quick Start Guide} 14\author{William Pence \thanks{HEASARC, NASA Goddard Space Flight Center}} 15 16\date{January 2003} 17 18\begin{document} 19 20\maketitle 21\tableofcontents 22 23% =================================================================== 24\section{Introduction} 25 26This document is intended to help you quickly start writing C programs 27to read and write FITS files using the CFITSIO library. It covers the 28most important CFITSIO routines that are needed to perform most types 29of operations on FITS files. For more complete information about these 30and all the other available routines in the library please refer to 31the ``CFITSIO User's Reference Guide'', which is available from the 32CFITSIO Web site at {\tt http://heasarc.gsfc.nasa.gov/fitsio}. 33 34For more general information about the FITS data format, refer to the 35following web page: 36http://heasarc.gsfc.nasa.gov/docs/heasarc/fits.html 37 38FITS stands for Flexible Image Transport System and is the standard 39file format used to store most astronomical data files. There are 2 40basic types of FITS files: images and tables. FITS images often 41contain a 2-dimensional array of pixels representing an image of a 42piece of the sky, but FITS images can also contain 1-D arrays (i.e, 43a spectrum or light curve), or 3-D arrays (a data cube), or 44even higher dimensional arrays of data. An image may also have zero 45dimensions, in which case it is referred to as a null or empty array. 46The supported datatypes for the image arrays are 8, 16, and 32-bit 47integers, and 32 and 64-bit floating point real numbers. Both signed 48and unsigned integers are supported. 49 50FITS tables contain rows and columns of data, similar to a 51spreadsheet. All the values in a particular column must have the same 52datatype. A cell of a column is not restricted to a single number, and 53instead can contain an array or vector of numbers. There are actually 542 subtypes of FITS tables: ASCII and binary. As the names imply, ASCII 55tables store the data values in an ASCII representation whereas binary 56tables store the data values in a more efficient machine-readable 57binary format. Binary tables are generally more compact and support 58more features (e.g., a wider range of datatypes, and vector columns) 59than ASCII tables. 60 61A single FITS file many contain multiple images or tables. Each table 62or image is called a Header-Data Unit, or HDU. The first HDU in a FITS 63file must be an image (but it may have zero axes) and is called the 64Primary Array. Any additional HDUs in the file (which are also 65referred to as `extensions') may contain either an image or a table. 66 67Every HDU contains a header containing keyword records. Each keyword 68record is 80 ASCII characters long and has the following format: 69 70\begin{verbatim} 71KEYWORD = value / comment string 72\end{verbatim} 73 74The keyword name can be up to 8 characters long (all uppercase). The 75value can be either an integer or floating point number, a logical 76value (T or F), or a character string enclosed in single quotes. Each 77header begins with a series of required keywords to describe the 78datatype and format of the following data unit, if any. Any number of 79other optional keywords can be included in the header to provide other 80descriptive information about the data. For the most part, the CFITSIO 81routines automatically write the required FITS keywords for each HDU, 82so you, the programmer, usually do not need to worry about them. 83 84% =================================================================== 85\section{Installing and Using CFITSIO} 86 87First, you should download the CFITSIO software and the set of example 88FITS utility programs from the web site at 89http://heasarc.gsfc.nasa.gov/fitsio. The example programs illustrate 90how to perform many common types of operations on FITS files using 91CFITSIO. They are also useful when writing a new program because it is 92often easier to take a copy of one of these utility programs as a 93template and then modify it for your own purposes, rather than writing 94the new program completely from scratch. 95 96To build the CFITSIO library on Unix platforms, `untar' the source code 97distribution file and then execute the following commands in the 98directory containing the source code: 99 100\begin{verbatim} 101> ./configure [--prefix=/target/installation/path] 102> make (or 'make shared') 103> make install (this step is optional) 104\end{verbatim} 105 106The optional 107'prefix' argument to configure gives the path to the directory where 108the CFITSIO library and include files should be installed via the later 109'make install' command. For example, 110 111\begin{verbatim} 112> ./configure --prefix=/usr1/local 113\end{verbatim} 114 115will cause the 'make install' command to copy the CFITSIO libcfitsio file 116to /usr1/local/lib and the necessary include files to /usr1/local/include 117(assuming of course that the process has permission to write to these 118directories). 119 120Pre-compiled versions of the CFITSIO DLL library are available for 121PCs. On Macintosh machines, refer to the README.MacOS file for 122instructions on building CFITSIO using CodeWarrior. 123 124Any programs that use CFITSIO must of course be linked with the CFITSIO 125library when creating the executable file. The exact procedure for 126linking a program depends on your software environment, but on Unix 127platforms, the command line to compile and link a program will look 128something like this: 129 130\begin{verbatim} 131gcc -o myprog myprog.c -L. -lcfitsio -lm -lnsl -lsocket 132\end{verbatim} 133 134You may not need to include all of the 'm', 'nsl', and 'socket' system 135libraries on your particular machine. To find out what libraries are 136required on your (Unix) system, type {\tt'make testprog'} and see what 137libraries are then included on the resulting link line. 138 139\newpage 140% =================================================================== 141\section{Example Programs} 142 143Before describing the individual CFITSIO routines in detail, it is 144instructive to first look at an actual program. The names of the 145CFITSIO routines are fairly descriptive (they all begin with {\tt 146fits\_}, so it should be reasonably clear what this program does: 147 148\begin{verbatim} 149---------------------------------------------------------------- 150 #include <string.h> 151 #include <stdio.h> 1521: #include "fitsio.h" 153 154 int main(int argc, char *argv[]) 155 { 1562: fitsfile *fptr; 157 char card[FLEN_CARD]; 1583: int status = 0, nkeys, ii; /* MUST initialize status */ 159 1604: fits_open_file(&fptr, argv[1], READONLY, &status); 161 fits_get_hdrspace(fptr, &nkeys, NULL, &status); 162 163 for (ii = 1; ii <= nkeys; ii++) { 164 fits_read_record(fptr, ii, card, &status); /* read keyword */ 165 printf("%s\n", card); 166 } 167 printf("END\n\n"); /* terminate listing with END */ 168 fits_close_file(fptr, &status); 169 170 if (status) /* print any error messages */ 1715: fits_report_error(stderr, status); 172 return(status); 173 } 174---------------------------------------------------------------- 175\end{verbatim} 176 177This program opens the specified FITS file and prints 178out all the header keywords in the current HDU. 179Some other points to notice about the program are: 180\begin{enumerate} 181 182\item 183The {\tt fitsio.h} header file must be included to define the 184various routines and symbols used in CFITSIO. 185 186\item 187 188The {\tt fitsfile} parameter is the first argument in almost every 189CFITSIO routine. It is a pointer to a structure (defined in {\tt 190fitsio.h}) that stores information about the particular FITS file that 191the routine will operate on. Memory for this structure is 192automatically allocated when the file is first opened or created, and 193is freed when the file is closed. 194 195\item 196Almost every CFITSIO routine has a {\tt status} parameter as the last 197argument. The status value is also usually returned as the value of the 198function itself. Normally status = 0, and a positive status value 199indicates an error of some sort. The status variable must always be 200initialized to zero before use, because if status is greater than zero 201on input then the CFITSIO routines will simply return without doing 202anything. This `inherited status' feature, where each CFITSIO routine 203inherits the status from the previous routine, makes it unnecessary to 204check the status value after every single CFITSIO routine call. 205Generally you should check the status after an especially important or 206complicated routine has been called, or after a block of 207closely related CFITSIO calls. This example program has taken this 208feature to the extreme and only checks the status value at the 209very end of the program. 210 211\item 212 213In this example program the file name to be opened is given as an 214argument on the command line ({\tt arg[1]}). If the file contains more 215than 1 HDU or extension, you can specify which particular HDU to be 216opened by enclosing the name or number of the HDU in square brackets 217following the root name of the file. For example, {\tt file.fts[0]} 218opens the primary array, while {\tt file.fts[2]} will move to and open 219the 2nd extension in the file, and {\tt file.fit[EVENTS]} will open the 220extension that has a {\tt EXTNAME = 'EVENTS'} keyword in the header. 221Note that on the Unix command line you must enclose the file name in 222single or double quote characters if the name contains special 223characters such as `[' or `]'. 224 225All of the CFITSIO routines which read or write header keywords, 226image data, or table data operate only within the currently opened 227HDU in the file. To read or write information in a different HDU you must 228first explicitly move to that HDU (see the {\tt fits\_movabs\_hdu} and 229{\tt fits\_movrel\_hdu} routines in section 4.3). 230 231\item 232 233The {\tt fits\_report\_error} routine provides a convenient way to print out 234diagnostic messages about any error that may have occurred. 235 236\end{enumerate} 237 238A set of example FITS utility programs are available from the CFITSIO 239web site at \newline 240http://heasarc.gsfc.nasa.gov/docs/software/fitsio/cexamples.html. 241These are real working programs which illustrate how to read, write, 242and modify FITS files using the CFITSIO library. Most of these 243programs are very short, containing only a few 10s of lines of 244executable code or less, yet they perform quite useful operations on 245FITS files. Running each program without any command line arguments 246will produce a short description of how to use the program. 247The currently available programs are: 248\begin{quote} 249fitscopy - copy a file 250\newline 251listhead - list header keywords 252\newline 253liststruc - show the structure of a FITS file. 254\newline 255modhead - write or modify a header keyword 256\newline 257imarith - add, subtract, multiply, or divide 2 images 258\newline 259imlist - list pixel values in an image 260\newline 261imstat - compute mean, min, and max pixel values in an image 262\newline 263tablist - display the contents of a FITS table 264\newline 265tabcalc - general table calculator 266\end{quote} 267 268\newpage 269 270% =================================================================== 271\section{CFITSIO Routines} 272 273This chapter describes the main CFITSIO routines that can be used to 274perform the most common types of operations on FITS files. 275 276% =================================================================== 277{\bf \subsection{Error Reporting}} 278 279\begin{verbatim} 280void fits_report_error(FILE *stream, int status) 281void fits_get_errstatus(int status, char *err_text) 282float fits_get_version(float *version) 283\end{verbatim} 284 285The first routine prints out information about any error that 286has occurred. Whenever any CFITSIO routine encounters an error it 287usually writes a message describing the nature of the error to an 288internal error message stack and then returns with a positive integer 289status value. Passing the error status value to this routine will 290cause a generic description of the error and all the messages 291from the internal CFITSIO error stack to be printed to the specified 292stream. The {\tt stream} parameter is usually set equal to 293{\tt "stdout"} or {\tt "stderr"}. 294 295The second routine simply returns a 30-character descriptive 296error message corresponding to the input status value. 297 298The last routine returns the current CFITSIO library version number. 299 300% =================================================================== 301{\bf \subsection{File Open/Close Routines}} 302 303\begin{verbatim} 304int fits_open_file( fitsfile **fptr, char *filename, int mode, int *status) 305int fits_open_data( fitsfile **fptr, char *filename, int mode, int *status) 306int fits_open_table(fitsfile **fptr, char *filename, int mode, int *status) 307int fits_open_image(fitsfile **fptr, char *filename, int mode, int *status) 308 309int fits_create_file(fitsfile **fptr, char *filename, int *status) 310int fits_close_file(fitsfile *fptr, int *status) 311\end{verbatim} 312 313These routines open or close a file. The first {\tt fitsfile} 314parameter in these and nearly every other CFITSIO routine is a pointer 315to a structure that CFITSIO uses to store relevant parameters about 316each opened file. You should never directly read or write any 317information in this structure. Memory for this structure is allocated 318automatically when the file is opened or created, and is freed when the 319file is closed. 320 321The {\tt mode} parameter in the {\tt fits\_open\_xxxx} set of routines 322can be set to either {\tt READONLY} or {\tt READWRITE} to select the 323type of file access that will be allowed. These symbolic constants are 324defined in {\tt fitsio.h}. 325 326The {\tt fits\_open\_file} routine opens the file and positions the internal 327file pointer to the beginning of the file, or to the specified 328extension if an extension name or number is appended to the file name 329(see the later section on ``CFITSIO File Names and Filters'' for a 330description of the syntax). {\tt fits\_open\_data} behaves similarly except 331that it will move to the first HDU containing significant data if a HDU 332name or number to open is not explicitly specified as part of the 333filename. It will move to the first IMAGE HDU with NAXIS greater than 3340, or the first table that does not contain the strings `GTI' (a Good 335Time Interval extension) or `OBSTABLE' in the EXTNAME keyword value. 336The {\tt fits\_open\_table} and {\tt fits\_open\_image} routines are similar 337except that they will move to the first significant table HDU or image 338HDU, respectively if a HDU name of number is not specified as part of 339the input file name. 340 341When opening an existing file, the {\tt filename} can include optional 342arguments, enclosed in square brackets that specify filtering 343operations that should be applied to the input file. For example, 344\begin{verbatim} 345 myfile.fit[EVENTS][counts > 0] 346\end{verbatim} 347opens the table in the EVENTS extension and creates a virtual table by 348selecting only those rows where the COUNTS column value is greater than 3490. See section 5 for more examples of these powerful filtering 350capabilities. 351 352In {\tt fits\_create\_file}, the {\tt filename} is simply the root name of 353the file to be created. You can overwrite an existing file by 354prefixing the name with a `!' character (on the Unix command line this 355must be prefixed with a backslash, as in \verb+`\!file.fit'+). 356If the file name ends with {\tt .gz} the file will be compressed 357using the gzip algorithm. If the 358filename is {\tt stdout} or {\tt "-"} (a single dash character) 359then the output file will be piped to the stdout stream. You can 360chain several tasks together by writing the output from the first task 361to {\tt stdout} and then reading the input file in the 2nd task from 362{\tt stdin} or {\tt "-"}. 363 364 365% =================================================================== 366{\bf \subsection{HDU-level Routines}} 367 368The routines listed in this section operate on Header-Data Units (HDUs) in a file. 369 370\begin{verbatim} 371_______________________________________________________________ 372int fits_get_num_hdus(fitsfile *fptr, int *hdunum, int *status) 373int fits_get_hdu_num(fitsfile *fptr, int *hdunum) 374\end{verbatim} 375 376The first routines returns the total number of HDUs in the FITS file, 377and the second routine returns the position of the currently opened HDU in 378the FITS file (starting with 1, not 0). 379 380\begin{verbatim} 381__________________________________________________________________________ 382int fits_movabs_hdu(fitsfile *fptr, int hdunum, int *hdutype, int *status) 383int fits_movrel_hdu(fitsfile *fptr, int nmove, int *hdutype, int *status) 384int fits_movnam_hdu(fitsfile *fptr, int hdutype, char *extname, 385 int extver, int *status) 386\end{verbatim} 387 388These routines enable you to move to a different HDU in the file. 389Most of the CFITSIO functions which read or write keywords or data 390operate only on the currently opened HDU in the file. The first 391routine moves to the specified absolute HDU number in the FITS 392file (the first HDU = 1), whereas the second routine moves a relative 393number of HDUs forward or backward from the currently open HDU. The 394{\tt hdutype} parameter returns the type of the newly opened HDU, and will 395be equal to one of these symbolic constant values: {\tt IMAGE\_HDU, 396ASCII\_TBL, or BINARY\_TBL}. {\tt hdutype} may be set to NULL 397if it is not needed. The third routine moves to the (first) HDU 398that matches the input extension type, name, and version number, 399as given by the {\tt XTENSION, EXTNAME} (or {\tt HDUNAME}) and {\tt EXTVER} keywords. 400If the input value of {\tt extver} = 0, then the version number will 401be ignored when looking for a matching HDU. 402 403\begin{verbatim} 404_________________________________________________________________ 405int fits_get_hdu_type(fitsfile *fptr, int *hdutype, int *status) 406\end{verbatim} 407 408Get the type of the current HDU in the FITS file: {\tt IMAGE\_HDU, 409ASCII\_TBL, or BINARY\_TBL}. 410 411\begin{verbatim} 412____________________________________________________________________ 413int fits_copy_hdu(fitsfile *infptr, fitsfile *outfptr, int morekeys, 414 int *status) 415int fits_copy_file(fitsfile *infptr, fitsfile *outfptr, int previous, 416 int current, int following, > int *status) 417\end{verbatim} 418 419The first routine copies the current HDU from the FITS file associated 420with infptr and appends it to the end of the FITS file associated with 421outfptr. Space may be reserved for {\tt morekeys} additional keywords 422in the output header. The second routine copies any HDUs previous 423to the current HDU, and/or the current HDU, and/or any HDUs following the 424current HDU, depending on the value (True or False) of {\tt previous, 425current}, and {\tt following}, respectively. For example, 426\begin{verbatim} 427 fits_copy_file(infptr, outfptr, 0, 1, 1, &status); 428\end{verbatim} 429will copy the current HDU and any HDUs that follow it from the input 430to the output file, but it will not copy any HDUs preceding the 431current HDU. 432 433 434\newpage 435% =================================================================== 436\subsection{Image I/O Routines} 437 438This section lists the more important CFITSIO routines which operate on 439FITS images. 440 441\begin{verbatim} 442_______________________________________________________________ 443int fits_get_img_type(fitsfile *fptr, int *bitpix, int *status) 444int fits_get_img_dim( fitsfile *fptr, int *naxis, int *status) 445int fits_get_img_size(fitsfile *fptr, int maxdim, long *naxes, 446 int *status) 447int fits_get_img_param(fitsfile *fptr, int maxdim, int *bitpix, 448 int *naxis, long *naxes, int *status) 449\end{verbatim} 450 451Get information about the currently opened image HDU. The first routine 452returns the datatype of the image as (defined by the {\tt BITPIX} 453keyword), which can have the following symbolic constant values: 454\begin{verbatim} 455 BYTE_IMG = 8 ( 8-bit byte pixels, 0 - 255) 456 SHORT_IMG = 16 (16 bit integer pixels) 457 LONG_IMG = 32 (32-bit integer pixels) 458 LONGLONG_IMG = 64 (64-bit integer pixels) 459 FLOAT_IMG = -32 (32-bit floating point pixels) 460 DOUBLE_IMG = -64 (64-bit floating point pixels) 461\end{verbatim} 462 463The second and third routines return the number of dimensions in the 464image (from the {\tt NAXIS} keyword), and the sizes of each dimension 465(from the {\tt NAXIS1, NAXIS2}, etc. keywords). The last routine 466simply combines the function of the first 3 routines. The input {\tt 467maxdim} parameter in this routine gives the maximum number dimensions 468that may be returned (i.e., the dimension of the {\tt naxes} 469array) 470 471\begin{verbatim} 472__________________________________________________________ 473int fits_create_img(fitsfile *fptr, int bitpix, int naxis, 474 long *naxes, int *status) 475\end{verbatim} 476 477Create an image HDU by writing the required keywords which define the 478structure of the image. The 2nd through 4th parameters specified the 479datatype, the number of dimensions, and the sizes of the dimensions. 480The allowed values of the {\tt bitpix} parameter are listed above in 481the description of the {\tt fits\_get\_img\_type} routine. If the FITS 482file pointed to by {\tt fptr} is empty (previously created with 483{\tt fits\_create\_file}) then this routine creates a primary array in 484the file, otherwise a new IMAGE extension is appended to end of the 485file following the other HDUs in the file. 486 487\begin{verbatim} 488______________________________________________________________ 489int fits_write_pix(fitsfile *fptr, int datatype, long *fpixel, 490 long nelements, void *array, int *status); 491 492int fits_write_pixnull(fitsfile *fptr, int datatype, long *fpixel, 493 long nelements, void *array, void *nulval, int *status); 494 495int fits_read_pix(fitsfile *fptr, int datatype, long *fpixel, 496 long nelements, void *nulval, void *array, 497 int *anynul, int *status) 498\end{verbatim} 499 500Read or write all or part of the FITS image. There are 2 different 501'write' pixel routines: The first simply writes the input array of pixels 502to the FITS file. The second is similar, except that it substitutes 503the appropriate null pixel value in the FITS file for any pixels 504which have a value equal to {\tt *nulval} (note that this parameter 505gives the address of the null pixel value, not the value itself). 506Similarly, when reading an image, CFITSIO will substitute the value 507given by {\tt nulval} for any undefined pixels in the image, unless 508{\tt nulval = NULL}, in which case no checks will be made for undefined 509pixels when reading the FITS image. 510 511The {\tt fpixel} parameter in these routines is an array which gives 512the coordinate in each dimension of the first pixel to be read or 513written, and {\tt nelements} is the total number of pixels to read or 514write. {\tt array} is the address of an array which either contains 515the pixel values to be written, or will hold the values of the pixels 516that are read. When reading, {\tt array} must have been allocated 517large enough to hold all the returned pixel values. These routines 518starts at the {\tt fpixel} location and then read or write the {\tt 519nelements} pixels, continuing on successive rows of the image if 520necessary. For example, to write an entire 2D image, set {\tt 521fpixel[0] = fpixel[1] = 1}, and {\tt nelements = NAXIS1 * NAXIS2}. Or 522to read just the 10th row of the image, set {\tt fpixel[0] = 1, 523fpixel[1] = 10}, and {\tt nelements = NAXIS1}. The {\tt datatype} 524parameter specifies the datatype of the C {\tt array} in the program, 525which need not be the same as the datatype of the FITS image itself. 526If the datatypes differ then CFITSIO will convert the data as it is 527read or written. The following symbolic constants are allowed for the 528value of {\tt datatype}: 529\begin{verbatim} 530 TBYTE unsigned char 531 TSBYTE signed char 532 TSHORT signed short 533 TUSHORT unsigned short 534 TINT signed int 535 TUINT unsigned int 536 TLONG signed long 537 TLONGLONG signed 8-byte integer 538 TULONG unsigned long 539 TFLOAT float 540 TDOUBLE double 541\end{verbatim} 542 543 544\begin{verbatim} 545_________________________________________________________________ 546int fits_write_subset(fitsfile *fptr, int datatype, long *fpixel, 547 long *lpixel, DTYPE *array, > int *status) 548 549int fits_read_subset(fitsfile *fptr, int datatype, long *fpixel, 550 long *lpixel, long *inc, void *nulval, void *array, 551 int *anynul, int *status) 552\end{verbatim} 553 554Read or write a rectangular section of the FITS image. These are very 555similar to {\tt fits\_write\_pix} and {\tt fits\_read\_pix} except that 556you specify the last pixel coordinate (the upper right corner of the 557section) instead of the number of pixels to be read. The read routine 558also has an {\tt inc} parameter which can be used to read only every 559{\tt inc-th} pixel along each dimension of the image. Normally {\tt 560inc[0] = inc[1] = 1} to read every pixel in a 2D image. To read every 561other pixel in the entire 2D image, set 562\begin{verbatim} 563 fpixel[0] = fpixel[1] = 1 564 lpixel[0] = {NAXIS1} 565 lpixel[1] = {NAXIS2} 566 inc[0] = inc[1] = 2 567\end{verbatim} 568 569Or, to read the 8th row of a 2D image, set 570\begin{verbatim} 571 fpixel[0] = 1 572 fpixel[1] = 8 573 lpixel[0] = {NAXIS1} 574 lpixel[1] = 8 575 inc[0] = inc[1] = 1 576\end{verbatim} 577 578\newpage 579% =================================================================== 580\subsection{Table I/O Routines} 581 582This section lists the most important CFITSIO routines which operate on 583FITS tables. 584 585\begin{verbatim} 586__________________________________________________________________________ 587int fits_create_tbl(fitsfile *fptr, int tbltype, long nrows, int tfields, 588 char *ttype[],char *tform[], char *tunit[], char *extname, int *status) 589\end{verbatim} 590 591Create a new table extension by writing the required keywords that 592define the table structure. The required null primary array 593will be created first if the file is initially completely empty. {\tt 594tbltype} defines the type of table and can have values of {\tt 595ASCII\_TBL or BINARY\_TBL}. Binary tables are generally preferred 596because they are more efficient and support a greater range of column 597datatypes than ASCII tables. 598 599The {\tt nrows} parameter gives the initial number of empty rows to be 600allocated for the table; this should normally be set to 0. The {\tt tfields} 601parameter gives the number of columns in the table (maximum = 999). 602The {\tt 603ttype, tform}, and {\tt tunit} parameters give the name, datatype, and 604physical units of each column, and {\tt extname} gives the name for the 605table (the value of the {\tt EXTNAME} keyword). 606The FITS Standard recommends that only 607letters, digits, and the underscore character be used in column names 608with no embedded spaces. It is recommended that all the column names 609in a given table be unique within the first 8 characters. 610 611The following table 612shows the TFORM column format values that are allowed in ASCII tables 613and in binary tables: 614\begin{verbatim} 615 ASCII Table Column Format Codes 616 ------------------------------- 617 (w = column width, d = no. of decimal places to display) 618 Aw - character string 619 Iw - integer 620 Fw.d - fixed floating point 621 Ew.d - exponential floating point 622 Dw.d - exponential floating point 623 624 Binary Table Column Format Codes 625 -------------------------------- 626 (r = vector length, default = 1) 627 rA - character string 628 rAw - array of strings, each of length w 629 rL - logical 630 rX - bit 631 rB - unsigned byte 632 rS - signed byte ** 633 rI - signed 16-bit integer 634 rU - unsigned 16-bit integer ** 635 rJ - signed 32-bit integer 636 rV - unsigned 32-bit integer ** 637 rK - signed 64-bit integer 638 rE - 32-bit floating point 639 rD - 64-bit floating point 640 rC - 32-bit complex pair 641 rM - 64-bit complex pair 642 643 ** The S, U and V format codes are not actual legal TFORMn values. 644 CFITSIO substitutes the somewhat more complicated set of 645 keywords that are used to represent unsigned integers or 646 signed bytes. 647 648\end{verbatim} 649 650The {\tt tunit} and {\tt extname} parameters are optional and 651may be set to NULL 652if they are not needed. 653 654Note that it may be easier to create a new table by copying the 655header from another existing table with {\tt fits\_copy\_header} rather 656than calling this routine. 657 658\begin{verbatim} 659_______________________________________________________________ 660int fits_get_num_rows(fitsfile *fptr, long *nrows, int *status) 661int fits_get_num_cols(fitsfile *fptr, int *ncols, int *status) 662\end{verbatim} 663 664Get the number of rows or columns in the current FITS table. The 665number of rows is given by the {\tt NAXIS2} keyword and the number of columns 666is given by the {\tt TFIELDS} keyword in the header of the table. 667 668\begin{verbatim} 669_______________________________________________________________ 670int fits_get_colnum(fitsfile *fptr, int casesen, char *template, 671 int *colnum, int *status) 672int fits_get_colname(fitsfile *fptr, int casesen, char *template, 673 char *colname, int *colnum, int *status) 674\end{verbatim} 675 676Get the column number (starting with 1, not 0) of the column whose 677name matches the specified template name. The only difference in 678these 2 routines is that the 2nd one also returns the name of the 679column that matched the template string. 680 681Normally, {\tt casesen} should 682be set to {\tt CASEINSEN}, but it may be set to {\tt CASESEN} to force 683the name matching to be case-sensitive. 684 685The input {\tt template} string gives the name of the desired column and 686may include wildcard characters: a `*' matches any sequence of 687characters (including zero characters), `?' matches any single 688character, and `\#' matches any consecutive string of decimal digits 689(0-9). If more than one column name in the table matches the template 690string, then the first match is returned and the status value will be 691set to {\tt COL\_NOT\_UNIQUE} as a warning that a unique match was not 692found. To find the next column that matches the template, call this 693routine again leaving the input status value equal to {\tt 694COL\_NOT\_UNIQUE}. Repeat this process until {\tt status = 695COL\_NOT\_FOUND} is returned. 696 697\begin{verbatim} 698_______________________________________________________________ 699int fits_get_coltype(fitsfile *fptr, int colnum, int *typecode, 700 long *repeat, long *width, int *status) 701 702int fits_get_eqcoltype(fitsfile *fptr, int colnum, int *typecode, 703 long *repeat, long *width, int *status) 704\end{verbatim} 705 706Return the datatype, vector repeat count, and the width in bytes of a 707single column element for column number {\tt colnum}. Allowed values 708for the returned datatype in ASCII tables are: {\tt TSTRING, TSHORT, 709TLONG, TFLOAT, and TDOUBLE}. Binary tables support these additional 710types: {\tt TLOGICAL, TBIT, TBYTE, TINT32BIT, TCOMPLEX and TDBLCOMPLEX}. The 711negative of the datatype code value is returned if it is a variable 712length array column. 713 714These 2 routines are similar, except that in the case of scaled 715integer columns the 2nd routine, fit\_get\_eqcoltype, returns the 716'equivalent' datatype that is needed to store the scaled values, which 717is not necessarily the same as the physical datatype of the unscaled values 718as stored in the FITS table. For example if a '1I' column in a binary 719table has TSCALn = 1 and TZEROn = 32768, then this column effectively 720contains unsigned short integer values, and thus the returned value of 721typecode will be TUSHORT, not TSHORT. Or, if TSCALn or TZEROn are not 722integers, then the equivalent datatype will be returned as TFLOAT or 723TDOUBLE, depending on the size of the integer. 724 725The repeat count is always 1 in ASCII tables. 726The 'repeat' parameter returns the vector repeat count on the binary 727table TFORMn keyword value. (ASCII table columns always have repeat 728= 1). The 'width' parameter returns the width in bytes of a single 729column element (e.g., a '10D' binary table column will have width = 7308, an ASCII table 'F12.2' column will have width = 12, and a binary 731table'60A' character string column will have width = 60); Note that 732this routine supports the local convention for specifying arrays of 733fixed length strings within a binary table character column using 734the syntax TFORM = 'rAw' where 'r' is the total number of 735characters (= the width of the column) and 'w' is the width of a 736unit string within the column. Thus if the column has TFORM = 737'60A12' then this means that each row of the table contains 7385 12-character substrings within the 60-character field, and thus 739in this case this routine will return typecode = TSTRING, repeat = 74060, and width = 12. The number of substings in any binary table 741character string field can be calculated by (repeat/width). 742A null pointer may be given for any of the output parameters that 743 are not needed. 744 745\begin{verbatim} 746____________________________________________________________________________ 747int fits_insert_rows(fitsfile *fptr, long firstrow, long nrows, int *status) 748int fits_delete_rows(fitsfile *fptr, long firstrow, long nrows, int *status) 749int fits_delete_rowrange(fitsfile *fptr, char *rangelist, int *status) 750int fits_delete_rowlist(fitsfile *fptr, long *rowlist, long nrows, int *stat) 751\end{verbatim} 752 753Insert or delete rows in a table. The blank rows are inserted 754immediately following row {\tt frow}. Set {\tt frow} = 0 to insert rows 755at the beginning of the table. The first 'delete' routine deletes {\tt 756nrows} rows beginning with row {\tt firstrow}. The 2nd delete routine 757takes an input string listing the rows or row ranges to be deleted 758(e.g., '2,4-7, 9-12'). The last delete routine takes an input long 759integer array that specifies each individual row to be deleted. The 760row lists must be sorted in ascending order. All these routines update 761the value of the {\tt NAXIS2} keyword to reflect the new number of rows 762in the table. 763 764\begin{verbatim} 765_________________________________________________________________________ 766int fits_insert_col(fitsfile *fptr, int colnum, char *ttype, char *tform, 767 int *status) 768int fits_insert_cols(fitsfile *fptr, int colnum, int ncols, char **ttype, 769 char **tform, int *status) 770 771int fits_delete_col(fitsfile *fptr, int colnum, int *status) 772\end{verbatim} 773 774Insert or delete columns in a table. {\tt colnum} gives the position 775of the column to be inserted or deleted (where the first column of the 776table is at position 1). {\tt ttype} and {\tt tform} give the column 777name and column format, where the allowed format codes are listed above 778in the description of the {\tt fits\_create\_table} routine. The 2nd 779'insert' routine inserts multiple columns, where {\tt ncols} is the 780number of columns to insert, and {\tt ttype} and {\tt tform} are 781arrays of string pointers in this case. 782 783\begin{verbatim} 784____________________________________________________________________ 785int fits_copy_col(fitsfile *infptr, fitsfile *outfptr, int incolnum, 786 int outcolnum, int create_col, int *status); 787\end{verbatim} 788 789Copy a column from one table HDU to another. If {\tt create\_col} = TRUE (i.e., not equal to zero), 790then a new column will be inserted in the output table at position 791{\tt outcolumn}, otherwise the values in the existing output column will be 792overwritten. 793 794\begin{verbatim} 795__________________________________________________________________________ 796int fits_write_col(fitsfile *fptr, int datatype, int colnum, long firstrow, 797 long firstelem, long nelements, void *array, int *status) 798int fits_write_colnull(fitsfile *fptr, int datatype, int colnum, 799 long firstrow, long firstelem, long nelements, 800 void *array, void *nulval, int *status) 801int fits_write_col_null(fitsfile *fptr, int colnum, long firstrow, 802 long firstelem, long nelements, int *status) 803 804int fits_read_col(fitsfile *fptr, int datatype, int colnum, long firstrow, 805 long firstelem, long nelements, void *nulval, void *array, 806 int *anynul, int *status) 807 808\end{verbatim} 809 810Write or read elements in column number {\tt colnum}, starting with row 811{\tt firstsrow} and element {\tt firstelem} (if it is a vector 812column). {\tt firstelem} is ignored if it is a scalar column. The {\tt 813nelements} number of elements are read or written continuing on 814successive rows of the table if necessary. {\tt array} is the address 815of an array which either contains the values to be written, or will 816hold the returned values that are read. When reading, {\tt array} must 817have been allocated large enough to hold all the returned values. 818 819There are 3 different 'write' column routines: The first simply writes 820the input array into the column. The second is similar, except that it 821substitutes the appropriate null pixel value in the column for any 822input array values which are equal to {\tt *nulval} (note that this 823parameter gives the address of the null pixel value, not the value 824itself). The third write routine sets the specified table elements 825to a null value. New rows will be automatical added to the table 826if the write operation extends beyond the current size of the table. 827 828When reading a column, CFITSIO will substitute the value given by {\tt 829nulval} for any undefined elements in the FITS column, unless {\tt 830nulval} or {\tt *nulval = NULL}, in which case no checks will be made 831for undefined values when reading the column. 832 833{\tt datatype} specifies the datatype of the C {\tt array} in the program, 834which need not be the same as the intrinsic datatype of the column in 835the FITS table. The following symbolic constants are allowed for the 836value of {\tt datatype}: 837 838\begin{verbatim} 839 TSTRING array of character string pointers 840 TBYTE unsigned char 841 TSHORT signed short 842 TUSHORT unsigned short 843 TINT signed int 844 TUINT unsigned int 845 TLONG signed long 846 TLONGLONG signed 8-byte integer 847 TULONG unsigned long 848 TFLOAT float 849 TDOUBLE double 850\end{verbatim} 851 852Note that {\tt TSTRING} corresponds to the C {\tt 853char**} datatype, i.e., a pointer to an array of pointers to an array 854of characters. 855 856Any column, regardless of it's intrinsic datatype, may be read as a 857{\tt TSTRING} character string. The display format of the returned 858strings will be determined by the {\tt TDISPn} keyword, if it exists, 859otherwise a default format will be used depending on the datatype of 860the column. The {\tt tablist} example utility program (available from 861the CFITSIO web site) uses this feature to display all the values in a 862FITS table. 863 864\begin{verbatim} 865_____________________________________________________________________ 866int fits_select_rows(fitsfile *infptr, fitsfile *outfptr, char *expr, 867 int *status) 868int fits_calculator(fitsfile *infptr, char *expr, fitsfile *outfptr, 869 char *colname, char *tform, int *status) 870\end{verbatim} 871 872These are 2 of the most powerful routines in the CFITSIO library. (See 873the full CFITSIO Reference Guide for a description of several related 874routines). These routines can perform complicated transformations on 875tables based on an input arithmetic expression which is evaluated for 876each row of the table. The first routine will select or copy rows of 877the table for which the expression evaluates to TRUE (i.e., not equal 878to zero). The second routine writes the value of the expression to a 879column in the output table. Rather than supplying the expression 880directly to these routines, the expression may also be written to a 881text file (continued over multiple lines if necessary) and the name of 882the file, prepended with a '@' character, may be supplied as the value 883of the 'expr' parameter (e.g. '@filename.txt'). 884 885The arithmetic expression may be a function of any column or keyword in 886the input table as shown in these examples: 887 888\begin{verbatim} 889Row Selection Expressions: 890 counts > 0 uses COUNTS column value 891 sqrt( X**2 + Y**2) < 10. uses X and Y column values 892 (X > 10) || (X < -10) && (Y == 0) used 'or' and 'and' operators 893 gtifilter() filter on Good Time Intervals 894 regfilter("myregion.reg") filter using a region file 895 @select.txt reads expression from a text file 896Calculator Expressions: 897 #row % 10 modulus of the row number 898 counts/#exposure Fn of COUNTS column and EXPOSURE keyword 899 dec < 85 ? cos(dec * #deg) : 0 Conditional expression: evaluates to 900 cos(dec) if dec < 85, else 0 901 (count{-1}+count+count{+1})/3. running mean of the count values in the 902 previous, current, and next rows 903 max(0, min(X, 1000)) returns a value between 0 - 1000 904 @calc.txt reads expression from a text file 905\end{verbatim} 906 907Most standard mathematical operators and functions are supported. If 908the expression includes the name of a column, than the value in the 909current row of the table will be used when evaluating the expression on 910each row. An offset to an adjacent row can be specified by including 911the offset value in curly brackets after the column name as shown in 912one of the examples. Keyword values can be included in the expression 913by preceding the keyword name with a `\#' sign. See Section 5 of this 914document for more discussion of the expression syntax. 915 916{\tt gtifilter} is a special function which tests whether the {\tt 917TIME} column value in the input table falls within one or more Good 918Time Intervals. By default, this function looks for a 'GTI' extension 919in the same file as the input table. The 'GTI' table contains {\tt START} 920and {\tt STOP} columns which define the range of 921each good time interval. See section 5.4.3 for more details. 922 923{\tt regfilter} is another special function which selects rows based on 924whether the spatial position associated with each row is located within 925in a specified region of the sky. By default, the {\tt X} and {\tt Y} 926columns in the input table are assumed to give the position of each row. 927The spatial region is defined in an ASCII text file whose name is given 928as the argument to the {\tt regfilter} function. See section 5.4.4 for 929more details. 930 931The {\tt infptr} and {\tt outfptr} parameters in these routines may 932point to the same table or to different tables. In {\tt 933fits\_select\_rows}, if the input and output tables are the same then 934the rows that do not satisfy the selection expression will be deleted 935from the table. Otherwise, if the output table is different from the 936input table then the selected rows will be copied from the input table 937to the output table. 938 939The output column in {\tt fits\_calculator} may or may not already 940exist. If it exists then the calculated values will be written to that 941column, overwriting the existing values. If the column doesn't exist 942then the new column will be appended to the output table. The {\tt tform} 943parameter can be used to specify the datatype of the new column (e.g., 944the {\tt TFORM} keyword value as in {\tt '1E', or '1J'}). If {\tt 945tform} = NULL then a default datatype will be used, depending on the 946expression. 947 948\begin{verbatim} 949_____________________________________________________________________ 950int fits_read_tblbytes(fitsfile *fptr, long firstrow, long firstchar, 951 long nchars, unsigned char *array, int *status) 952int fits_write_tblbytes (fitsfile *fptr, long firstrow, long firstchar, 953 long nchars, unsigned char *array, int *status) 954\end{verbatim} 955 956These 2 routines provide low-level access to tables and are mainly 957useful as an efficient way to copy rows of a table from one file to 958another. These routines simply read or write the specified number of 959consecutive characters (bytes) in a table, without regard for column 960boundaries. For example, to read or write the first row of a table, 961set {\tt firstrow = 1, firstchar = 1}, and {\tt nchars = NAXIS1} where 962the length of a row is given by the value of the {\tt NAXIS1} header 963keyword. When reading a table, {\tt array} must have been declared at 964least {\tt nchars} bytes long to hold the returned string of bytes. 965 966\newpage 967% =================================================================== 968\subsection{Header Keyword I/O Routines} 969\nopagebreak 970The following routines read and write header keywords in the current HDU. 971\nopagebreak 972 973\begin{verbatim} 974____________________________________________________________________ 975int fits_get_hdrspace(fitsfile *fptr, int *keysexist, int *morekeys, 976 int *status) 977\end{verbatim} 978\nopagebreak 979Return the number of existing keywords (not counting the mandatory END 980keyword) and the amount of empty space currently available for more 981keywords. The {\tt morekeys} parameter may be set to NULL if it's value is 982not needed. 983 984\begin{verbatim} 985___________________________________________________________________________ 986int fits_read_record(fitsfile *fptr, int keynum, char *record, int *status) 987int fits_read_card(fitsfile *fptr, char *keyname, char *record, int *status) 988int fits_read_key(fitsfile *fptr, int datatype, char *keyname, 989 void *value, char *comment, int *status) 990 991int fits_find_nextkey(fitsfile *fptr, char **inclist, int ninc, 992 char **exclist, int nexc, char *card, int *status) 993 994int fits_read_key_unit(fitsfile *fptr, char *keyname, char *unit, 995 int *status) 996\end{verbatim} 997 998These routines all read a header record in the current HDU. The first 999routine reads keyword number {\tt keynum} (where the first keyword is 1000at position 1). This routine is most commonly used when sequentially 1001reading every record in the header from beginning to end. The 2nd and 10023rd routines read the named keyword and return either the whole 1003record, or the keyword value and comment string. In each case any 1004non-significant trailing blank characters in the strings are truncated. 1005 1006Wild card characters (*, ?, and \#) may be used when specifying the name 1007of the keyword to be read, in which case the first matching keyword is 1008returned. 1009 1010The {\tt datatype} parameter specifies the C datatype of the returned 1011keyword value and can have one of the following symbolic constant 1012values: {\tt TSTRING, TLOGICAL} (== int), {\tt TBYTE}, {\tt TSHORT}, 1013{\tt TUSHORT}, {\tt TINT}, {\tt TUINT}, {\tt TLONG}, {\tt TULONG}, {\tt 1014TFLOAT}, {\tt TDOUBLE}, {\tt TCOMPLEX}, and {\tt TDBLCOMPLEX}. Data 1015type conversion will be performed for numeric values if the intrinsic 1016FITS keyword value does not have the same datatype. The {\tt comment} 1017parameter may be set equal to NULL if the comment string is not 1018needed. 1019 1020The 4th routine provides an easy way to find all the keywords in the 1021header that match one of the name templates in {\tt inclist} and do not 1022match any of the name templates in {\tt exclist}. {\tt ninc} and {\tt 1023nexc} are the number of template strings in {\tt inclist} and {\tt 1024exclist}, respectively. Wild cards (*, ?, and \#) may be used in the 1025templates to match multiple keywords. Each time this routine is called 1026it returns the next matching 80-byte keyword record. It returns status 1027= {\tt KEY\_NO\_EXIST} if there are no more matches. 1028 1029The 5th routine returns the keyword value units string, if any. 1030The units are recorded at the beginning of the keyword comment field 1031enclosed in square brackets. 1032\begin{verbatim} 1033_______________________________________________________________ 1034int fits_write_key(fitsfile *fptr, int datatype, char *keyname, 1035 void *value, char *comment, int *status) 1036int fits_update_key(fitsfile *fptr, int datatype, char *keyname, 1037 void *value, char *comment, int *status) 1038int fits_write_record(fitsfile *fptr, char *card, int *status) 1039 1040int fits_modify_comment(fitsfile *fptr, char *keyname, char *comment, 1041 int *status) 1042int fits_write_key_unit(fitsfile *fptr, char *keyname, char *unit, 1043 int *status) 1044 1045\end{verbatim} 1046 1047Write or modify a keyword in the header of the current HDU. The 1048first routine appends the new keyword to the end of the header, whereas 1049the second routine will update the value and comment fields of the 1050keyword if it already exists, otherwise it behaves like the first 1051routine and appends the new keyword. Note that {\tt value} gives the 1052address to the value and not the value itself. The {\tt datatype} 1053parameter specifies the C datatype of the keyword value and may have 1054any of the values listed in the description of the keyword reading 1055routines, above. A NULL may be entered for the comment parameter, in 1056which case the keyword comment field will be unmodified or left 1057blank. 1058 1059The third routine is more primitive and simply writes the 80-character 1060{\tt card} record to the header. It is the programmer's responsibility 1061in this case to ensure that the record conforms to all the FITS format 1062requirements for a header record. 1063 1064The fourth routine modifies the comment string in an existing keyword, 1065and the last routine writes or updates the keyword units string for an 1066existing keyword. (The units are recorded at the beginning of the 1067keyword comment field enclosed in square brackets). 1068 1069\begin{verbatim} 1070___________________________________________________________________ 1071int fits_write_comment(fitsfile *fptr, char *comment, int *status) 1072int fits_write_history(fitsfile *fptr, char *history, int *status) 1073int fits_write_date(fitsfile *fptr, int *status) 1074\end{verbatim} 1075 1076Write a {\tt COMMENT, HISTORY}, or {\tt DATE} keyword to the current 1077header. The {\tt COMMENT} keyword is typically used to write a comment 1078about the file or the data. The {\tt HISTORY} keyword is typically 1079used to provide information about the history of the processing 1080procedures that have been applied to the data. The {\tt comment} or 1081{\tt history} string will be continued over multiple keywords if it is 1082more than 70 characters long. 1083 1084The {\tt DATE} keyword is used to record the date and time that the 1085FITS file was created. Note that this file creation date is usually 1086different from the date of the observation which obtained the data in 1087the FITS file. The {\tt DATE} keyword value is a character string in 1088'yyyy-mm-ddThh:mm:ss' format. If a {\tt DATE} keyword already exists in 1089the header, then this routine will update the value with the current 1090system date. 1091 1092\begin{verbatim} 1093___________________________________________________________________ 1094int fits_delete_record(fitsfile *fptr, int keynum, int *status) 1095int fits_delete_key(fitsfile *fptr, char *keyname, int *status) 1096\end{verbatim} 1097 1098Delete a keyword record. The first routine deletes a keyword at a 1099specified position (the first keyword is at position 1, not 0), 1100whereas the second routine deletes the named keyword. 1101 1102\begin{verbatim} 1103_______________________________________________________________________ 1104int fits_copy_header(fitsfile *infptr, fitsfile *outfptr, int *status) 1105\end{verbatim} 1106 1107Copy all the header keywords from the current HDU associated with 1108infptr to the current HDU associated with outfptr. If the current 1109output HDU is not empty, then a new HDU will be appended to the output 1110file. The output HDU will then have the identical structure as the 1111input HDU, but will contain no data. 1112 1113\newpage 1114% =================================================================== 1115\subsection{Utility Routines} 1116 1117This section lists the most important CFITSIO general utility routines. 1118 1119\begin{verbatim} 1120___________________________________________________________________ 1121int fits_write_chksum( fitsfile *fptr, int *status) 1122int fits_verify_chksum(fitsfile *fptr, int *dataok, int *hduok, int *status) 1123\end{verbatim} 1124 1125These routines compute or validate the checksums for the currenrt 1126HDU. The {\tt DATASUM} keyword is used to store the numerical value of 1127the 32-bit, 1's complement checksum for the data unit alone. The {\tt 1128CHECKSUM} keyword is used to store the ASCII encoded COMPLEMENT of the 1129checksum for the entire HDU. Storing the complement, rather than the 1130actual checksum, forces the checksum for the whole HDU to equal zero. 1131If the file has been modified since the checksums were computed, then 1132the HDU checksum will usually not equal zero. 1133 1134The returned {\tt dataok} and {\tt hduok} parameters will have a value 1135= 1 if the data or HDU is verified correctly, a value = 0 if the 1136{\tt DATASUM} or {\tt CHECKSUM} keyword is not present, or value = -1 if the 1137computed checksum is not correct. 1138 1139 1140\begin{verbatim} 1141___________________________________________________________________ 1142int fits_parse_value(char *card, char *value, char *comment, int *status) 1143int fits_get_keytype(char *value, char *dtype, int *status) 1144int fits_get_keyclass(char *card) 1145int fits_parse_template(char *template, char *card, int *keytype, int *status) 1146 1147\end{verbatim} 1148 1149{\tt fits\_parse\_value} parses the input 80-chararacter header keyword record, returning 1150the value (as a literal character string) and comment strings. If the 1151keyword has no value (columns 9-10 not equal to '= '), then a null 1152value string is returned and the comment string is set equal to column 11539 - 80 of the input string. 1154 1155{\tt fits\_get\_keytype} parses the keyword value string to determine its 1156datatype. {\tt dtype} returns with a value of 'C', 'L', 'I', 'F' or 1157'X', for character string, logical, integer, floating point, or 1158complex, respectively. 1159 1160{\tt fits\_get\_keyclass} returns a classification code that indicates 1161the classification type of the input keyword record (e.g., a required 1162structural keyword, a TDIM keyword, a WCS keyword, a comment keyword, 1163etc. See the CFITSIO Reference Guide for a list of the different 1164classification codes. 1165 1166{\tt fits\_parse\_template} takes an input free format keyword template 1167string and returns a formatted 80*char record that satisfies all the 1168FITS requirements for a header keyword record. The template should 1169generally contain 3 tokens: the keyword name, the keyword value, and 1170the keyword comment string. The returned {\tt keytype} parameter 1171indicates whether the keyword is a COMMENT keyword or not. See the 1172CFITSIO Reference Guide for more details. 1173 1174\newpage 1175% =================================================================== 1176\section{CFITSIO File Names and Filters} 1177 1178\subsection{Creating New Files} 1179 1180When creating a new output file on magnetic disk with {\tt 1181fits\_create\_file} the following features are supported. 1182\begin{itemize} 1183\item Overwriting, or 'Clobbering' an Existing File 1184 1185If the filename is preceded by an exclamation 1186point (!) then if that file already exists it will be deleted prior to 1187creating the new FITS file. Otherwise if there is an existing file 1188with the same name, CFITSIO will not overwrite the existing file and 1189will return an error status code. Note that the exclamation point is 1190a special UNIX character, so if it is used on the command line rather 1191than entered at a task prompt, it must be preceded by a backslash to 1192force the UNIX shell to pass it verbatim to the application program. 1193 1194\item Compressed Output Files 1195 1196If the output disk file name ends with the suffix '.gz', then CFITSIO 1197will compress the file using the gzip compression algorithm before 1198writing it to disk. This can reduce the amount of disk space used by 1199the file. Note that this feature requires that the uncompressed file 1200be constructed in memory before it is compressed and written to disk, 1201so it can fail if there is insufficient available memory. 1202 1203One can also specify that any images written to the output file should 1204be compressed using the newly developed `tile-compression' algorithm by 1205appending `[compress]' to the name of the disk file (as in 1206{\tt myfile.fits[compress]}). Refer to the CFITSIO User's Reference Guide 1207for more information about this new image compression format. 1208 1209\item Using a Template to Create a New FITS File 1210 1211The structure of any new FITS file that is to be created may be defined 1212in an ASCII template file. If the name of the template file is 1213appended to the name of the FITS file itself, enclosed in parenthesis 1214(e.g., {\tt 'newfile.fits(template.txt)'}) then CFITSIO will create a 1215FITS file with that structure before opening it for the application to 1216use. The template file basically defines the dimensions and data type 1217of the primary array and any IMAGE extensions, and the names and data 1218types of the columns in any ASCII or binary table extensions. The 1219template file can also be used to define any optional keywords that 1220should be written in any of the HDU headers. The image pixel values 1221and table entry values are all initialized to zero. The application 1222program can then write actual data into the HDUs. See the CFITSIO 1223Reference Guide for for a complete description of the template file 1224syntax. 1225 1226\item Creating a Temporary Scratch File in Memory 1227 1228It is sometimes useful to create a temporary output file when testing 1229an application program. If the name of the file to be created is 1230specified as {\tt mem:} then CFITSIO will create the file in 1231memory where it will persist only until the program closes the file. 1232Use of this {\tt mem:} output file usually enables the program to run 1233faster, and of course the output file does not use up any disk space. 1234 1235 1236\end{itemize} 1237 1238\subsection{Opening Existing Files} 1239 1240When opening a file with {\tt fits\_open\_file}, CFITSIO can read a 1241variety of different input file formats and is not restricted to only 1242reading FITS format files from magnetic disk. The following types of 1243input files are all supported: 1244 1245\begin{itemize} 1246\item FITS files compressed with {\tt zip, gzip} or {\tt compress} 1247 1248If CFITSIO cannot find the specified file to open it will automatically 1249look for a file with the same rootname but with a {\tt .gz, .zip}, or 1250{\tt .Z} extension. If it finds such a compressed file, it will 1251allocate a block of memory and uncompress the file into that memory 1252space. The application program will then transparently open this 1253virtual FITS file in memory. Compressed 1254files can only be opened with 'readonly', not 'readwrite' file access. 1255 1256\item FITS files on the internet, using {\tt ftp} or {\tt http} URLs 1257 1258Simply provide the full URL as the name of the file that you want to 1259open. For example,\linebreak {\tt 1260ftp://legacy.gsfc.nasa.gov/software/fitsio/c/testprog.std}\linebreak 1261will open the CFITSIO test FITS file that is located on the {\tt 1262legacy} machine. These files can only be opened with 'readonly' file 1263access. 1264 1265\item FITS files on {\tt stdin} or {\tt stdout} file streams 1266 1267If the name of the file to be opened is {\tt 'stdin'} or {\tt '-'} (a 1268single dash character) then CFITSIO will read the file from the 1269standard input stream. Similarly, if the output file name is {\tt 1270'stdout'} or {\tt '-'}, then the file will be written to the standard 1271output stream. In addition, if the output filename is {\tt 1272'stdout.gz'} or {\tt '-.gz'} then it will be gzip compressed before 1273being written to stdout. This mechanism can be used to pipe FITS files 1274from one task to another without having to write an intermediary FITS 1275file on magnetic disk. 1276 1277\item FITS files that exist only in memory, or shared memory. 1278 1279In some applications, such as real time data acquisition, you may want 1280to have one process write a FITS file into a certain section of 1281computer memory, and then be able to open that file in memory with 1282another process. There is a specialized CFITSIO open routine called 1283{\tt fits\_open\_memfile} that can be used for this purpose. See the 1284``CFITSIO User's Reference Guide'' for more details. 1285 1286\item IRAF format images (with {\tt .imh} file extensions) 1287 1288CFITSIO supports reading IRAF format images by converting them on the 1289fly into FITS images in memory. The application program then reads 1290this virtual FITS format image in memory. There is currently no 1291support for writing IRAF format images, or for reading or writing IRAF 1292tables. 1293 1294\item Image arrays in raw binary format 1295 1296If the input file is a raw binary data array, then CFITSIO will convert 1297it on the fly into a virtual FITS image with the basic set of required 1298header keywords before it is opened by the application program. In 1299this case the data type and dimensions of the image must be specified 1300in square brackets following the filename (e.g. {\tt 1301rawfile.dat[ib512,512]}). The first character inside the brackets 1302defines the datatype of the array: 1303 1304\begin{verbatim} 1305 b 8-bit unsigned byte 1306 i 16-bit signed integer 1307 u 16-bit unsigned integer 1308 j 32-bit signed integer 1309 r or f 32-bit floating point 1310 d 64-bit floating point 1311\end{verbatim} 1312An optional second character specifies the byte order of the array 1313values: b or B indicates big endian (as in FITS files and the native 1314format of SUN UNIX workstations and Mac PCs) and l or L indicates 1315little endian (native format of DEC OSF workstations and IBM PCs). If 1316this character is omitted then the array is assumed to have the native 1317byte order of the local machine. These datatype characters are then 1318followed by a series of one or more integer values separated by commas 1319which define the size of each dimension of the raw array. Arrays with 1320up to 5 dimensions are currently supported. 1321 1322Finally, a byte offset to the position of the first pixel in the data 1323file may be specified by separating it with a ':' from the last 1324dimension value. If omitted, it is assumed that the offset = 0. This 1325parameter may be used to skip over any header information in the file 1326that precedes the binary data. Further examples: 1327 1328\begin{verbatim} 1329 raw.dat[b10000] 1-dimensional 10000 pixel byte array 1330 raw.dat[rb400,400,12] 3-dimensional floating point big-endian array 1331 img.fits[ib512,512:2880] reads the 512 x 512 short integer array in a 1332 FITS file, skipping over the 2880 byte header 1333\end{verbatim} 1334 1335\end{itemize} 1336\newpage 1337 1338\subsection{Image Filtering} 1339 1340\subsubsection{Extracting a subsection of an image} 1341 1342When specifying the name of an image to be opened, you can select a 1343rectangular subsection of the image to be extracted and opened by the 1344application program. The application program then opens a virtual 1345image that only contains the pixels within the specified subsection. 1346To do this, specify the the range of pixels (start:end) along each axis 1347to be extracted from the original image enclosed in square brackets. 1348You can also specify an optional pixel increment (start:end:step) for 1349each axis of the input image. A pixel step = 1 will be assumed if it 1350is not specified. If the starting pixel is larger then the end pixel, 1351then the image will be flipped (producing a mirror image) along that 1352dimension. An asterisk, '*', may be used to specify the entire range 1353of an axis, and '-*' will flip the entire axis. In the following 1354examples, assume that {\tt myfile.fits} contains a 512 x 512 pixel 2D 1355image. 1356 1357\begin{verbatim} 1358 myfile.fits[201:210, 251:260] - opens a 10 x 10 pixel subimage. 1359 1360 myfile.fits[*, 512:257] - opens a 512 x 256 image consisting of 1361 all the columns in the input image, but only rows 257 1362 through 512. The image will be flipped along the Y axis 1363 since the starting row is greater than the ending 1364 row. 1365 1366 myfile.fits[*:2, 512:257:2] - creates a 256 x 128 pixel image. 1367 Similar to the previous example, but only every other row 1368 and column is read from the input image. 1369 1370 myfile.fits[-*, *] - creates an image containing all the rows and 1371 columns in the input image, but flips it along the X 1372 axis. 1373\end{verbatim} 1374 1375If the array to be opened is in an Image extension, and not in the 1376primary array of the file, then you need to specify the extension 1377name or number in square brackets before giving the subsection range, 1378as in {\tt myfile.fits[1][-*, *]} to read the image in the 1379first extension in the file. 1380 1381\subsubsection{Create an Image by Binning Table Columns} 1382 1383You can also create and open a virtual image by binning the values in a 1384pair of columns of a FITS table (in other words, create a 2-D histogram 1385of the values in the 2 columns). This technique is often used in X-ray 1386astronomy where each detected X-ray photon during an observation is 1387recorded in a FITS table. There are typically 2 columns in the table 1388called {\tt X} and {\tt Y} which record the pixel location of that 1389event in a virtual 2D image. To create an image from this table, one 1390just scans the X and Y columns and counts up how many photons were 1391recorded in each pixel of the image. When table binning is specified, 1392CFITSIO creates a temporary FITS primary array in memory by computing 1393the histogram of the values in the specified columns. After the 1394histogram is computed the original FITS file containing the table is 1395closed and the temporary FITS primary array is opened and passed to the 1396application program. Thus, the application program never sees the 1397original FITS table and only sees the image in the new temporary file 1398(which has no extensions). 1399 1400The table binning specifier is enclosed in square brackets following 1401the root filename and table extension name or number and begins with 1402the keyword 'bin', as in: \newline 1403{\tt 'myfile.fits[events][bin (X,Y)]'}. In 1404this case, the X and Y columns in the 'events' table extension are 1405binned up to create the image. The size of the image is usually 1406determined by the {\tt TLMINn} and {\tt TLMAXn} header keywords which 1407give the minimum and maximum allowed pixel values in the columns. For 1408instance if {\tt TLMINn = 1} and {\tt TLMAXn = 4096} for both columns, this would 1409generate a 4096 x 4096 pixel image by default. This is rather large, 1410so you can also specify a pixel binning factor to reduce the image 1411size. For example specifying , {\tt '[bin (X,Y) = 16]'} will use a 1412binning factor of 16, which will produce a 256 x 256 pixel image in the 1413previous example. 1414 1415If the TLMIN and TLMAX keywords don't exist, or you want to override 1416their values, you can specify the image range and binning factor 1417directly, as in {\tt '[bin X = 1:4096:16, Y=1:4096:16]'}. You can also 1418specify the datatype of the created image by appending a b, i, j, r, or 1419d (for 8-bit byte, 16-bit integers, 32-bit integer, 32-bit floating 1420points, or 64-bit double precision floating point, respectively) to 1421the 'bin' keyword (e.g. {\tt '[binr (X,Y)]'} creates a floating point 1422image). If the datatype is not specified then a 32-bit integer image 1423will be created by default. 1424 1425If the column name is not specified, then CFITSIO will first try to use 1426the 'preferred column' as specified by the CPREF keyword if it exists 1427(e.g., 'CPREF = 'DETX,DETY'), otherwise column names 'X', 'Y' will be 1428assumed for the 2 axes. 1429 1430Note that this binning specifier is not restricted to only 2D images 1431and can be used to create 1D, 3D, or 4D images as well. It is also 1432possible to specify a weighting factor that is applied during the 1433binning. Please refer to the ``CFITSIO User's Reference Guide'' for 1434more details on these advanced features. 1435\newpage 1436 1437\subsection{Table Filtering} 1438 1439\subsubsection{Column and Keyword Filtering} 1440 1441The column or keyword filtering specifier is used to modify the 1442column structure and/or the header keywords in the HDU that was 1443selected with the previous HDU location specifier. It can 1444be used to perform the following types of operations. 1445 1446\begin{itemize} 1447\item 1448Append a new column to a table by giving the column name, optionally 1449followed by the datatype in parentheses, followed by an equals sign and 1450the arithmetic expression to be used to compute the value. The 1451datatype is specified using the same syntax that is allowed for the 1452value of the FITS TFORMn keyword (e.g., 'I', 'J', 'E', 'D', etc. for 1453binary tables, and 'I8', F12.3', 'E20.12', etc. for ASCII tables). If 1454the datatype is not specified then a default datatype will be chosen 1455depending on the expression. 1456 1457\item 1458Create a new header keyword by giving the keyword name, preceded by a 1459pound sign '\#', followed by an equals sign and an arithmetic 1460expression for the value of the keyword. The expression may be a 1461function of other header keyword values. The comment string for the 1462keyword may be specified in parentheses immediately following the 1463keyword name. 1464 1465\item 1466Overwrite the values in an existing column or keyword by giving the 1467name followed by an equals sign and an arithmetic expression. 1468 1469\item 1470Select a set of columns to be included in the filtered file by listing 1471the column names separated with semi-colons. Wild card characters may 1472be used in the column names to match multiple columns. Any other 1473columns in the input table will not appear in the filtered file. 1474 1475\item 1476Delete a column or keyword by listing the name preceded by a minus sign 1477or an exclamation mark (!) 1478 1479\item 1480Rename an existing column or keyword with the syntax 'NewName == 1481OldName'. 1482 1483\end{itemize} 1484 1485The column filtering specifier is enclosed in square brackets and 1486begins with the string 'col'. Multiple operations can be performed 1487by separating them with semi-colons. For complex or commonly used 1488operations, you can write the column filter to a text file, and then 1489use it by giving the name of the text file, preceded by a '@' 1490character. 1491 1492Some examples: 1493 1494\begin{verbatim} 1495 [col PI=PHA * 1.1 + 0.2] - creates new PI column from PHA values 1496 1497 [col rate = counts/exposure] - creates or overwrites the rate column by 1498 dividing the counts column by the 1499 EXPOSURE keyword value. 1500 1501 [col TIME; X; Y] - only the listed columns will appear 1502 in the filtered file 1503 1504 [col Time;*raw] - include the Time column and any other 1505 columns whose name ends with 'raw'. 1506 1507 [col -TIME; Good == STATUS] - deletes the TIME column and 1508 renames the STATUS column to GOOD 1509 1510 [col @colfilt.txt] - uses the filtering expression in 1511 the colfilt.txt text file 1512\end{verbatim} 1513 1514The original file is not changed by this filtering operation, and 1515instead the modifications are made on a temporary copy of the input 1516FITS file (usually in memory), which includes a copy of all the other 1517HDUs in the input file. The original input file is closed and the 1518application program opens the filtered copy of the file. 1519 1520\subsubsection{Row Filtering} 1521 1522The row filter is used to select a subset of the rows from a table 1523based on a boolean expression. A temporary new FITS file is created on 1524the fly (usually in memory) which contains only those rows for which 1525the row filter expression evaluates to true (i.e., not equal to zero). 1526The primary array and any other extensions in the input file are also 1527copied to the temporary file. The original FITS file is closed and the 1528new temporary file is then opened by the application program. 1529 1530The row filter expression is enclosed in square brackets following the 1531file name and extension name. For example, {\tt 1532'file.fits[events][GRADE==50]'} selects only those rows in the EVENTS 1533table where the GRADE column value is equal to 50). 1534 1535The row filtering expression can be an arbitrarily complex series of 1536operations performed on constants, keyword values, and column data 1537taken from the specified FITS TABLE extension. The expression 1538also can be written into a text file and then used by giving the 1539filename preceded by a '@' character, as in 1540{\tt '[@rowfilt.txt]'}. 1541 1542Keyword and column data are referenced by name. Any string of 1543characters not surrounded by quotes (ie, a constant string) or 1544followed by an open parentheses (ie, a function name) will be 1545initially interpreted as a column name and its contents for the 1546current row inserted into the expression. If no such column exists, 1547a keyword of that name will be searched for and its value used, if 1548found. To force the name to be interpreted as a keyword (in case 1549there is both a column and keyword with the same name), precede the 1550keyword name with a single pound sign, '\#', as in {\tt \#NAXIS2}. Due to 1551the generalities of FITS column and keyword names, if the column or 1552keyword name contains a space or a character which might appear as 1553an arithmetic term then inclose the name in '\$' characters as in 1554{\tt \$MAX PHA\$} or {\tt \#\$MAX-PHA\$}. The names are case insensitive. 1555 1556To access a table entry in a row other than the current one, follow 1557the column's name with a row offset within curly braces. For 1558example, {\tt'PHA\{-3\}'} will evaluate to the value of column PHA, 3 rows 1559above the row currently being processed. One cannot specify an 1560absolute row number, only a relative offset. Rows that fall outside 1561the table will be treated as undefined, or NULLs. 1562 1563Boolean operators can be used in the expression in either their 1564Fortran or C forms. The following boolean operators are available: 1565 1566\begin{verbatim} 1567 "equal" .eq. .EQ. == "not equal" .ne. .NE. != 1568 "less than" .lt. .LT. < "less than/equal" .le. .LE. <= =< 1569 "greater than" .gt. .GT. > "greater than/equal" .ge. .GE. >= => 1570 "or" .or. .OR. || "and" .and. .AND. && 1571 "negation" .not. .NOT. ! "approx. equal(1e-7)" ~ 1572\end{verbatim} 1573 1574Note that the exclamation point, '!', is a special UNIX character, so 1575if it is used on the command line rather than entered at a task 1576prompt, it must be preceded by a backslash to force the UNIX shell to 1577ignore it. 1578 1579The expression may also include arithmetic operators and functions. 1580Trigonometric functions use radians, not degrees. The following 1581arithmetic operators and functions can be used in the expression 1582(function names are case insensitive): 1583 1584 1585\begin{verbatim} 1586 "addition" + "subtraction" - 1587 "multiplication" * "division" / 1588 "negation" - "exponentiation" ** ^ 1589 "absolute value" abs(x) "cosine" cos(x) 1590 "sine" sin(x) "tangent" tan(x) 1591 "arc cosine" arccos(x) "arc sine" arcsin(x) 1592 "arc tangent" arctan(x) "arc tangent" arctan2(x,y) 1593 "exponential" exp(x) "square root" sqrt(x) 1594 "natural log" log(x) "common log" log10(x) 1595 "modulus" i % j "random # [0.0,1.0)" random() 1596 "minimum" min(x,y) "maximum" max(x,y) 1597 "if-then-else" b?x:y 1598\end{verbatim} 1599 1600 1601The following type casting operators are available, where the 1602inclosing parentheses are required and taken from the C language 1603usage. Also, the integer to real casts values to double precision: 1604 1605\begin{verbatim} 1606 "real to integer" (int) x (INT) x 1607 "integer to real" (float) i (FLOAT) i 1608\end{verbatim} 1609 1610 1611Several constants are built in for use in numerical 1612expressions: 1613 1614 1615\begin{verbatim} 1616 #pi 3.1415... #e 2.7182... 1617 #deg #pi/180 #row current row number 1618 #null undefined value #snull undefined string 1619\end{verbatim} 1620 1621A string constant must be enclosed in quotes as in 'Crab'. The 1622"null" constants are useful for conditionally setting table values to 1623a NULL, or undefined, value (For example, {\tt "col1==-99 ? \#NULL : 1624col1"}). 1625 1626There is also a function for testing if two values are close to 1627each other, i.e., if they are "near" each other to within a user 1628specified tolerance. The arguments, {\tt value\_1} and {\tt value\_2} can be 1629integer or real and represent the two values who's proximity is 1630being tested to be within the specified tolerance, also an integer 1631or real: 1632 1633\begin{verbatim} 1634 near(value_1, value_2, tolerance) 1635\end{verbatim} 1636 1637When a NULL, or undefined, value is encountered in the FITS table, 1638the expression will evaluate to NULL unless the undefined value is 1639not actually required for evaluation, e.g. "TRUE .or. NULL" 1640evaluates to TRUE. The following two functions allow some NULL 1641detection and handling: 1642 1643\begin{verbatim} 1644 ISNULL(x) 1645 DEFNULL(x,y) 1646\end{verbatim} 1647 1648The former returns a boolean value of TRUE if the argument x is 1649NULL. The later "defines" a value to be substituted for NULL 1650values; it returns the value of x if x is not NULL, otherwise it 1651returns the value of y. 1652 1653Bit masks can be used to select out rows from bit columns ({\tt TFORMn = 1654\#X}) in FITS files. To represent the mask, binary, octal, and hex 1655formats are allowed: 1656 1657\begin{verbatim} 1658 binary: b0110xx1010000101xxxx0001 1659 octal: o720x1 -> (b111010000xxx001) 1660 hex: h0FxD -> (b00001111xxxx1101) 1661\end{verbatim} 1662 1663In all the representations, an x or X is allowed in the mask as a 1664wild card. Note that the x represents a different number of wild 1665card bits in each representation. All representations are case 1666insensitive. 1667 1668To construct the boolean expression using the mask as the boolean 1669equal operator described above on a bit table column. For example, 1670if you had a 7 bit column named flags in a FITS table and wanted 1671all rows having the bit pattern 0010011, the selection expression 1672would be: 1673 1674 1675\begin{verbatim} 1676 flags == b0010011 1677 or 1678 flags .eq. b10011 1679\end{verbatim} 1680 1681It is also possible to test if a range of bits is less than, less 1682than equal, greater than and greater than equal to a particular 1683boolean value: 1684 1685 1686\begin{verbatim} 1687 flags <= bxxx010xx 1688 flags .gt. bxxx100xx 1689 flags .le. b1xxxxxxx 1690\end{verbatim} 1691 1692Notice the use of the x bit value to limit the range of bits being 1693compared. 1694 1695It is not necessary to specify the leading (most significant) zero 1696(0) bits in the mask, as shown in the second expression above. 1697 1698Bit wise AND, OR and NOT operations are also possible on two or 1699more bit fields using the '\&'(AND), '$|$'(OR), and the '!'(NOT) 1700operators. All of these operators result in a bit field which can 1701then be used with the equal operator. For example: 1702 1703 1704\begin{verbatim} 1705 (!flags) == b1101100 1706 (flags & b1000001) == bx000001 1707\end{verbatim} 1708 1709Bit fields can be appended as well using the '+' operator. Strings 1710can be concatenated this way, too. 1711 1712\subsubsection{Good Time Interval Filtering} 1713 1714 A common filtering method involves selecting rows which have a time 1715 value which lies within what is called a Good Time Interval or GTI. 1716 The time intervals are defined in a separate FITS table extension 1717 which contains 2 columns giving the start and stop time of each 1718 good interval. The filtering operation accepts only those rows of 1719 the input table which have an associated time which falls within 1720 one of the time intervals defined in the GTI extension. A high 1721 level function, gtifilter(a,b,c,d), is available which evaluates 1722 each row of the input table and returns TRUE or FALSE depending 1723 whether the row is inside or outside the good time interval. The 1724 syntax is 1725 1726\begin{verbatim} 1727 gtifilter( [ "gtifile" [, expr [, "STARTCOL", "STOPCOL" ] ] ] ) 1728\end{verbatim} 1729 where each "[]" demarks optional parameters. Note that the quotes 1730 around the gtifile and START/STOP column are required. Either single 1731 or double quote characters may be used. The gtifile, 1732 if specified, can be blank ("") which will mean to use the first 1733 extension with the name "*GTI*" in the current file, a plain 1734 extension specifier (eg, "+2", "[2]", or "[STDGTI]") which will be 1735 used to select an extension in the current file, or a regular 1736 filename with or without an extension specifier which in the latter 1737 case will mean to use the first extension with an extension name 1738 "*GTI*". Expr can be any arithmetic expression, including simply 1739 the time column name. A vector time expression will produce a 1740 vector boolean result. STARTCOL and STOPCOL are the names of the 1741 START/STOP columns in the GTI extension. If one of them is 1742 specified, they both must be. 1743 1744 In its simplest form, no parameters need to be provided -- default 1745 values will be used. The expression {\tt "gtifilter()"} is equivalent to 1746 1747\begin{verbatim} 1748 gtifilter( "", TIME, "*START*", "*STOP*" ) 1749\end{verbatim} 1750 This will search the current file for a GTI extension, filter the 1751 TIME column in the current table, using START/STOP times taken from 1752 columns in the GTI extension with names containing the strings 1753 "START" and "STOP". The wildcards ('*') allow slight variations in 1754 naming conventions such as "TSTART" or "STARTTIME". The same 1755 default values apply for unspecified parameters when the first one 1756 or two parameters are specified. The function automatically 1757 searches for TIMEZERO/I/F keywords in the current and GTI 1758 extensions, applying a relative time offset, if necessary. 1759 1760\subsubsection{Spatial Region Filtering} 1761 1762 Another common filtering method selects rows based on whether the 1763 spatial position associated with each row is located within a given 1764 2-dimensional region. The syntax for this high-level filter is 1765 1766\begin{verbatim} 1767 regfilter( "regfilename" [ , Xexpr, Yexpr [ , "wcs cols" ] ] ) 1768\end{verbatim} 1769 where each "[ ]" demarks optional parameters. The region file name 1770 is required and must be enclosed in quotes. The remaining 1771 parameters are optional. The region file is an ASCII text file 1772 which contains a list of one or more geometric shapes (circle, 1773 ellipse, box, etc.) which defines a region on the celestial sphere 1774 or an area within a particular 2D image. The region file is 1775 typically generated using an image display program such as fv/POW 1776 (distribute by the HEASARC), or ds9 (distributed by the Smithsonian 1777 Astrophysical Observatory). Users should refer to the documentation 1778 provided with these programs for more details on the syntax used in 1779 the region files. 1780 1781 In its simpliest form, (e.g., {\tt regfilter("region.reg")} ) the 1782 coordinates in the default 'X' and 'Y' columns will be used to 1783 determine if each row is inside or outside the area specified in 1784 the region file. Alternate position column names, or expressions, 1785 may be entered if needed, as in 1786 1787\begin{verbatim} 1788 regfilter("region.reg", XPOS, YPOS) 1789\end{verbatim} 1790 Region filtering can be applied most unambiguously if the positions 1791 in the region file and in the table to be filtered are both give in 1792 terms of absolute celestial coordinate units. In this case the 1793 locations and sizes of the geometric shapes in the region file are 1794 specified in angular units on the sky (e.g., positions given in 1795 R.A. and Dec. and sizes in arcseconds or arcminutes). Similarly, 1796 each row of the filtered table will have a celestial coordinate 1797 associated with it. This association is usually implemented using 1798 a set of so-called 'World Coordinate System' (or WCS) FITS keywords 1799 that define the coordinate transformation that must be applied to 1800 the values in the 'X' and 'Y' columns to calculate the coordinate. 1801 1802 Alternatively, one can perform spatial filtering using unitless 1803 'pixel' coordinates for the regions and row positions. In this 1804 case the user must be careful to ensure that the positions in the 2 1805 files are self-consistent. A typical problem is that the region 1806 file may be generated using a binned image, but the unbinned 1807 coordinates are given in the event table. The ROSAT events files, 1808 for example, have X and Y pixel coordinates that range from 1 - 1809 15360. These coordinates are typically binned by a factor of 32 to 1810 produce a 480x480 pixel image. If one then uses a region file 1811 generated from this image (in image pixel units) to filter the 1812 ROSAT events file, then the X and Y column values must be converted 1813 to corresponding pixel units as in: 1814 1815\begin{verbatim} 1816 regfilter("rosat.reg", X/32.+.5, Y/32.+.5) 1817\end{verbatim} 1818 Note that this binning conversion is not necessary if the region 1819 file is specified using celestial coordinate units instead of pixel 1820 units because CFITSIO is then able to directly compare the 1821 celestial coordinate of each row in the table with the celestial 1822 coordinates in the region file without having to know anything 1823 about how the image may have been binned. 1824 1825 The last "wcs cols" parameter should rarely be needed. If supplied, 1826 this string contains the names of the 2 columns (space or comma 1827 separated) which have the associated WCS keywords. If not supplied, 1828 the filter will scan the X and Y expressions for column names. 1829 If only one is found in each expression, those columns will be 1830 used, otherwise an error will be returned. 1831 1832 These region shapes are supported (names are case insensitive): 1833 1834\begin{verbatim} 1835 Point ( X1, Y1 ) <- One pixel square region 1836 Line ( X1, Y1, X2, Y2 ) <- One pixel wide region 1837 Polygon ( X1, Y1, X2, Y2, ... ) <- Rest are interiors with 1838 Rectangle ( X1, Y1, X2, Y2, A ) | boundaries considered 1839 Box ( Xc, Yc, Wdth, Hght, A ) V within the region 1840 Diamond ( Xc, Yc, Wdth, Hght, A ) 1841 Circle ( Xc, Yc, R ) 1842 Annulus ( Xc, Yc, Rin, Rout ) 1843 Ellipse ( Xc, Yc, Rx, Ry, A ) 1844 Elliptannulus ( Xc, Yc, Rinx, Riny, Routx, Routy, Ain, Aout ) 1845 Sector ( Xc, Yc, Amin, Amax ) 1846\end{verbatim} 1847 where (Xc,Yc) is the coordinate of the shape's center; (X\#,Y\#) are 1848 the coordinates of the shape's edges; Rxxx are the shapes' various 1849 Radii or semimajor/minor axes; and Axxx are the angles of rotation 1850 (or bounding angles for Sector) in degrees. For rotated shapes, the 1851 rotation angle can be left off, indicating no rotation. Common 1852 alternate names for the regions can also be used: rotbox = box; 1853 rotrectangle = rectangle; (rot)rhombus = (rot)diamond; and pie 1854 = sector. When a shape's name is preceded by a minus sign, '-', 1855 the defined region is instead the area *outside* its boundary (ie, 1856 the region is inverted). All the shapes within a single region 1857 file are OR'd together to create the region, and the order is 1858 significant. The overall way of looking at region files is that if 1859 the first region is an excluded region then a dummy included region 1860 of the whole detector is inserted in the front. Then each region 1861 specification as it is processed overrides any selections inside of 1862 that region specified by previous regions. Another way of thinking 1863 about this is that if a previous excluded region is completely 1864 inside of a subsequent included region the excluded region is 1865 ignored. 1866 1867 The positional coordinates may be given either in pixel units, 1868 decimal degrees or hh:mm:ss.s, dd:mm:ss.s units. The shape sizes 1869 may be given in pixels, degrees, arcminutes, or arcseconds. Look 1870 at examples of region file produced by fv/POW or ds9 for further 1871 details of the region file format. 1872 1873\subsubsection{Example Row Filters} 1874 1875\begin{verbatim} 1876 [double && mag <= 5.0] - Extract all double stars brighter 1877 than fifth magnitude 1878 1879 [#row >= 125 && #row <= 175] - Extract row numbers 125 through 175 1880 1881 [abs(sin(theta * #deg)) < 0.5] - Extract all rows having the 1882 absolute value of the sine of theta 1883 less than a half where the angles 1884 are tabulated in degrees 1885 1886 [@rowFilter.txt] - Extract rows using the expression 1887 contained within the text file 1888 rowFilter.txt 1889 1890 [gtifilter()] - Search the current file for a GTI 1891 extension, filter the TIME 1892 column in the current table, using 1893 START/STOP times taken from 1894 columns in the GTI extension 1895 1896 [regfilter("pow.reg")] - Extract rows which have a coordinate 1897 (as given in the X and Y columns) 1898 within the spatial region specified 1899 in the pow.reg region file. 1900\end{verbatim} 1901 1902\newpage 1903\subsection{Combined Filtering Examples} 1904 1905The previous sections described all the individual types of filters 1906that may be applied to the input file. In this section we show 1907examples which combine several different filters at once. These 1908examples all use the {\tt fitscopy} program that is distributed with 1909the CFITSIO code. It simply copies the input file to the output file. 1910 1911\begin{verbatim} 1912fitscopy rosat.fit out.fit 1913\end{verbatim} 1914 1915This trivial example simply makes an identical copy of the input 1916rosat.fit file without any filtering. 1917 1918\begin{verbatim} 1919fitscopy 'rosat.fit[events][col Time;X;Y][#row < 1000]' out.fit 1920\end{verbatim} 1921 1922The output file contains only the Time, X, and Y columns, and only 1923the first 999 rows from the 'EVENTS' table extension of the input file. 1924All the other HDUs in the input file are copied to the output file 1925without any modification. 1926 1927\begin{verbatim} 1928fitscopy 'rosat.fit[events][PI < 50][bin (Xdet,Ydet) = 16]' image.fit 1929\end{verbatim} 1930 1931This creates an output image by binning the Xdet and Ydet columns of 1932the events table with a pixel binning factor of 16. Only the rows 1933which have a PI energy less than 50 are used to construct this image. 1934The output image file contains a primary array image without any 1935extensions. 1936 1937\begin{verbatim} 1938fitscopy 'rosat.fit[events][gtifilter() && regfilter("pow.reg")]' out.fit 1939\end{verbatim} 1940 1941The filtering expression in this example uses the {\tt gtifilter} 1942function to test whether the TIME column value in each row is within 1943one of the Good Time Intervals defined in the GTI extension in the same 1944input file, and also uses the {\tt regfilter} function to test if the 1945position associated with each row (derived by default from the values 1946in the X and Y columns of the events table) is located within the area 1947defined in the {\tt pow.reg} text region file (which was previously 1948created with the {\tt fv/POW} image display program). Only the rows 1949which satisfy both tests are copied to the output table. 1950 1951\begin{verbatim} 1952fitscopy 'r.fit[evt][PI<50]' stdout | fitscopy stdin[evt][col X,Y] out.fit 1953\end{verbatim} 1954 1955In this somewhat convoluted example, fitscopy is used to first select 1956the rows from the evt extension which have PI less than 50 and write the 1957resulting table out to the stdout stream. This is piped to a 2nd 1958instance of fitscopy (with the Unix `$|$' pipe command) which reads that 1959filtered FITS file from the stdin stream and copies only the X and Y 1960columns from the evt table to the output file. 1961 1962\begin{verbatim} 1963fitscopy 'r.fit[evt][col RAD=sqrt((X-#XCEN)**2+(Y-#YCEN)**2)][rad<100]' out.fit 1964\end{verbatim} 1965 1966This example first creates a new column called RAD which gives the 1967distance between the X,Y coordinate of each event and the coordinate 1968defined by the XCEN and YCEN keywords in the header. Then, only those 1969rows which have a distance less than 100 are copied to the output 1970table. In other words, only the events which are located within 100 1971pixel units from the (XCEN, YCEN) coordinate are copied to the output 1972table. 1973 1974\begin{verbatim} 1975fitscopy 'ftp://heasarc.gsfc.nasa.gov/rosat.fit[events][bin (X,Y)=16]' img.fit 1976\end{verbatim} 1977 1978This example bins the X and Y columns of the hypothetical ROSAT file 1979at the HEASARC ftp site to create the output image. 1980 1981\begin{verbatim} 1982fitscopy 'raw.fit[i512,512][101:110,51:60]' image.fit 1983\end{verbatim} 1984 1985This example converts the 512 x 512 pixel raw binary 16-bit integer 1986image to a FITS file and copies a 10 x 10 pixel subimage from it to the 1987output FITS image. 1988 1989\newpage 1990\section{CFITSIO Error Status Codes} 1991 1992The following table lists all the error status codes used by CFITSIO. 1993Programmers are encouraged to use the symbolic mnemonics (defined in 1994the file fitsio.h) rather than the actual integer status values to 1995improve the readability of their code. 1996 1997\begin{verbatim} 1998 Symbolic Const Value Meaning 1999 -------------- ----- ----------------------------------------- 2000 0 OK, no error 2001 SAME_FILE 101 input and output files are the same 2002 TOO_MANY_FILES 103 tried to open too many FITS files at once 2003 FILE_NOT_OPENED 104 could not open the named file 2004 FILE_NOT_CREATED 105 could not create the named file 2005 WRITE_ERROR 106 error writing to FITS file 2006 END_OF_FILE 107 tried to move past end of file 2007 READ_ERROR 108 error reading from FITS file 2008 FILE_NOT_CLOSED 110 could not close the file 2009 ARRAY_TOO_BIG 111 array dimensions exceed internal limit 2010 READONLY_FILE 112 Cannot write to readonly file 2011 MEMORY_ALLOCATION 113 Could not allocate memory 2012 BAD_FILEPTR 114 invalid fitsfile pointer 2013 NULL_INPUT_PTR 115 NULL input pointer to routine 2014 SEEK_ERROR 116 error seeking position in file 2015 2016 BAD_URL_PREFIX 121 invalid URL prefix on file name 2017 TOO_MANY_DRIVERS 122 tried to register too many IO drivers 2018 DRIVER_INIT_FAILED 123 driver initialization failed 2019 NO_MATCHING_DRIVER 124 matching driver is not registered 2020 URL_PARSE_ERROR 125 failed to parse input file URL 2021 2022 SHARED_BADARG 151 bad argument in shared memory driver 2023 SHARED_NULPTR 152 null pointer passed as an argument 2024 SHARED_TABFULL 153 no more free shared memory handles 2025 SHARED_NOTINIT 154 shared memory driver is not initialized 2026 SHARED_IPCERR 155 IPC error returned by a system call 2027 SHARED_NOMEM 156 no memory in shared memory driver 2028 SHARED_AGAIN 157 resource deadlock would occur 2029 SHARED_NOFILE 158 attempt to open/create lock file failed 2030 SHARED_NORESIZE 159 shared memory block cannot be resized at the moment 2031 2032 HEADER_NOT_EMPTY 201 header already contains keywords 2033 KEY_NO_EXIST 202 keyword not found in header 2034 KEY_OUT_BOUNDS 203 keyword record number is out of bounds 2035 VALUE_UNDEFINED 204 keyword value field is blank 2036 NO_QUOTE 205 string is missing the closing quote 2037 BAD_KEYCHAR 207 illegal character in keyword name or card 2038 BAD_ORDER 208 required keywords out of order 2039 NOT_POS_INT 209 keyword value is not a positive integer 2040 NO_END 210 couldn't find END keyword 2041 BAD_BITPIX 211 illegal BITPIX keyword value 2042 BAD_NAXIS 212 illegal NAXIS keyword value 2043 BAD_NAXES 213 illegal NAXISn keyword value 2044 BAD_PCOUNT 214 illegal PCOUNT keyword value 2045 BAD_GCOUNT 215 illegal GCOUNT keyword value 2046 BAD_TFIELDS 216 illegal TFIELDS keyword value 2047 NEG_WIDTH 217 negative table row size 2048 NEG_ROWS 218 negative number of rows in table 2049 COL_NOT_FOUND 219 column with this name not found in table 2050 BAD_SIMPLE 220 illegal value of SIMPLE keyword 2051 NO_SIMPLE 221 Primary array doesn't start with SIMPLE 2052 NO_BITPIX 222 Second keyword not BITPIX 2053 NO_NAXIS 223 Third keyword not NAXIS 2054 NO_NAXES 224 Couldn't find all the NAXISn keywords 2055 NO_XTENSION 225 HDU doesn't start with XTENSION keyword 2056 NOT_ATABLE 226 the CHDU is not an ASCII table extension 2057 NOT_BTABLE 227 the CHDU is not a binary table extension 2058 NO_PCOUNT 228 couldn't find PCOUNT keyword 2059 NO_GCOUNT 229 couldn't find GCOUNT keyword 2060 NO_TFIELDS 230 couldn't find TFIELDS keyword 2061 NO_TBCOL 231 couldn't find TBCOLn keyword 2062 NO_TFORM 232 couldn't find TFORMn keyword 2063 NOT_IMAGE 233 the CHDU is not an IMAGE extension 2064 BAD_TBCOL 234 TBCOLn keyword value < 0 or > rowlength 2065 NOT_TABLE 235 the CHDU is not a table 2066 COL_TOO_WIDE 236 column is too wide to fit in table 2067 COL_NOT_UNIQUE 237 more than 1 column name matches template 2068 BAD_ROW_WIDTH 241 sum of column widths not = NAXIS1 2069 UNKNOWN_EXT 251 unrecognizable FITS extension type 2070 UNKNOWN_REC 252 unknown record; 1st keyword not SIMPLE or XTENSION 2071 END_JUNK 253 END keyword is not blank 2072 BAD_HEADER_FILL 254 Header fill area contains non-blank chars 2073 BAD_DATA_FILL 255 Illegal data fill bytes (not zero or blank) 2074 BAD_TFORM 261 illegal TFORM format code 2075 BAD_TFORM_DTYPE 262 unrecognizable TFORM datatype code 2076 BAD_TDIM 263 illegal TDIMn keyword value 2077 BAD_HEAP_PTR 264 invalid BINTABLE heap pointer is out of range 2078 2079 BAD_HDU_NUM 301 HDU number < 1 or > MAXHDU 2080 BAD_COL_NUM 302 column number < 1 or > tfields 2081 NEG_FILE_POS 304 tried to move to negative byte location in file 2082 NEG_BYTES 306 tried to read or write negative number of bytes 2083 BAD_ROW_NUM 307 illegal starting row number in table 2084 BAD_ELEM_NUM 308 illegal starting element number in vector 2085 NOT_ASCII_COL 309 this is not an ASCII string column 2086 NOT_LOGICAL_COL 310 this is not a logical datatype column 2087 BAD_ATABLE_FORMAT 311 ASCII table column has wrong format 2088 BAD_BTABLE_FORMAT 312 Binary table column has wrong format 2089 NO_NULL 314 null value has not been defined 2090 NOT_VARI_LEN 317 this is not a variable length column 2091 BAD_DIMEN 320 illegal number of dimensions in array 2092 BAD_PIX_NUM 321 first pixel number greater than last pixel 2093 ZERO_SCALE 322 illegal BSCALE or TSCALn keyword = 0 2094 NEG_AXIS 323 illegal axis length < 1 2095 2096 NOT_GROUP_TABLE 340 Grouping function error 2097 HDU_ALREADY_MEMBER 341 2098 MEMBER_NOT_FOUND 342 2099 GROUP_NOT_FOUND 343 2100 BAD_GROUP_ID 344 2101 TOO_MANY_HDUS_TRACKED 345 2102 HDU_ALREADY_TRACKED 346 2103 BAD_OPTION 347 2104 IDENTICAL_POINTERS 348 2105 BAD_GROUP_ATTACH 349 2106 BAD_GROUP_DETACH 350 2107 2108 NGP_NO_MEMORY 360 malloc failed 2109 NGP_READ_ERR 361 read error from file 2110 NGP_NUL_PTR 362 null pointer passed as an argument. 2111 Passing null pointer as a name of 2112 template file raises this error 2113 NGP_EMPTY_CURLINE 363 line read seems to be empty (used 2114 internally) 2115 NGP_UNREAD_QUEUE_FULL 364 cannot unread more then 1 line (or single 2116 line twice) 2117 NGP_INC_NESTING 365 too deep include file nesting (infinite 2118 loop, template includes itself ?) 2119 NGP_ERR_FOPEN 366 fopen() failed, cannot open template file 2120 NGP_EOF 367 end of file encountered and not expected 2121 NGP_BAD_ARG 368 bad arguments passed. Usually means 2122 internal parser error. Should not happen 2123 NGP_TOKEN_NOT_EXPECT 369 token not expected here 2124 2125 BAD_I2C 401 bad int to formatted string conversion 2126 BAD_F2C 402 bad float to formatted string conversion 2127 BAD_INTKEY 403 can't interpret keyword value as integer 2128 BAD_LOGICALKEY 404 can't interpret keyword value as logical 2129 BAD_FLOATKEY 405 can't interpret keyword value as float 2130 BAD_DOUBLEKEY 406 can't interpret keyword value as double 2131 BAD_C2I 407 bad formatted string to int conversion 2132 BAD_C2F 408 bad formatted string to float conversion 2133 BAD_C2D 409 bad formatted string to double conversion 2134 BAD_DATATYPE 410 illegal datatype code value 2135 BAD_DECIM 411 bad number of decimal places specified 2136 NUM_OVERFLOW 412 overflow during datatype conversion 2137 DATA_COMPRESSION_ERR 413 error compressing image 2138 DATA_DECOMPRESSION_ERR 414 error uncompressing image 2139 2140 BAD_DATE 420 error in date or time conversion 2141 2142 PARSE_SYNTAX_ERR 431 syntax error in parser expression 2143 PARSE_BAD_TYPE 432 expression did not evaluate to desired type 2144 PARSE_LRG_VECTOR 433 vector result too large to return in array 2145 PARSE_NO_OUTPUT 434 data parser failed not sent an out column 2146 PARSE_BAD_COL 435 bad data encounter while parsing column 2147 PARSE_BAD_OUTPUT 436 Output file not of proper type 2148 2149 ANGLE_TOO_BIG 501 celestial angle too large for projection 2150 BAD_WCS_VAL 502 bad celestial coordinate or pixel value 2151 WCS_ERROR 503 error in celestial coordinate calculation 2152 BAD_WCS_PROJ 504 unsupported type of celestial projection 2153 NO_WCS_KEY 505 celestial coordinate keywords not found 2154 APPROX_WCS_KEY 506 approximate wcs keyword values were returned 2155\end{verbatim} 2156 2157\end{document} 2158