Util::FITSfile (version 1.9)

Constructor

• new(filename, ext, specifications)
  If the extension, "ext", is omitted, it defaults to "1". The primary HDU is "0". Note that ext can be either numerical or symbolic - i.e. it may refer to the EXTNAME keyword of the desired extension. Don't use brackets around the extension name argument. Specifications are optional FITSIO file selection specifications. These do need to include all punctuation, such as brackets. See the FITSIO extended filename syntax documentation for more information.

Accessors

• name()
  Get or set the name of the file without decorations.

• ext(newfile)
  Get or set the FITS extension.

• specs()
  Get or set the file specifiers.

• cols()
  Sets the current column specifier which is handed off to most FTOOLS verbatim. This is a space separated list of column names, though sometimes only a single column name is appropriate. Multiple arguments will be concatenated. If there are too many columns to fit on a single parameter line, this method will dump them to a temporary file.

• rows()
  Set the row specifier which is handed verbatim to most FTOOLS. By convention it can consist of a comma-separated list of single numbers or ranges specified as two numbers separated by a "-". However, note that sometimes only a single number is appropriate.

• dump_separator()
  Set the character used as a field separator in fdump. You probably don't need to worry about this unless you have a table with a string column containing a "|" character.

• get_dump_separator()
  Return the current fdump field separator. See above.

• fullname()
  Return the file name will all extended filename syntax decorations attached.

• checksum_tool()
  Get or set the Util::Tool object in the class data which will be used to calculate site-independant checksums.

Methods

• ncols()
  Return the number of columns currently specified. If no columns are specified, it returns the total number of columns in the table.

• nrows()
  Return the number of rows currently specified. If no rows are specified, it returns the total number of rows in the table.

• nhdus()
  Returns the total number of HDUs in the FITS file.

• list_hdus()
  Returns a list of all the HDUs in the FITS file.

• find_column(col)
  Returns the number corresponding to a given column name or 0 if the column is not contained in the file.

• dump_table()
  Dump the contents of a table into a single long string. This is really just an interface to the fdump FTOOL. This low level access method is mostly for internal use. Most table access should be done with the "table" method.

• table()
  Returns the currently specified rows and columns of the table. If only one column and row are specified, it returns that value - either as a scalar or as an array with a single value, depending on the context. If more than one row or column are specified, returns the values in a a single array cycling fastest over rows. Note that with two columns this can be convenient if you want to put the values into a hash. For three or more columns you may need to do some awkward reshuffling.

• isOrdered(unique)
  Check if the current column is in order.
  • returns 1 if the column is in order
  • returns 0 if the column is not in order or if there is an error from cktime The default column name is "TIME" if none is explicitly specified.
  An empty table is considered to be ordered.

• sort()
  Sort a table by the current column(s). The default column is "TIME" if none is explicitly specified.

• keyword(key, value, comment)
  Read or set a keyword value from the header
  • If one argument is given, read the keyword of that name.
  • If two or more arguments are given, write the value in the second argument to the keyword and return a reference to this object.
  • If three arguments are given, the third is the inline keyword comment.
  .

• begin_many_keywords()
  Begin a long set of keywords to add using fmodhead instead of fparkey The keywords themselves are specified using the keyword method.

• end_many_keywords()
  End a long list of keyword modifications and apply those modifications to the file. See the begin_many_keywords method.

• keywords()
  Get a hash of all the keywords in an HDU.

• import_header(source, [except|include], key1, key2...)
  Copy the header from another file into this one, optionally omitting all the listed keywords.

• column_comment(comment)
  Modify the in-line comment for the current column of a FITS table. Note that the current columns must be set to a single column name.

• site_independant_checksum()
  This method generates a site-independant checksum for a FITS file. It does this by dumping the headers of the file, deleting keywords such as DATE, ORIGIN, and CHECKSUM, and generating a checksum of that. Note that if FITS data checksums have been generated, this takes the data parts of the file into account.

• copy(newfile)
  Run fcopy to copy this FITS file to another. This is mostly useful if you want to use the extended file name syntax to filter a file. If no filename is given, fcopy will overwrite the input file, effectively screening in place.

• extract(newfile)
  This is similar to the copy method, except that it only copies the current HDU of the FITS file. It is basicly a wrapper aourn fextract.

• append_to(file)
  Append the current extension to another FITS file using "fappend".

• verify()
  Run fverify on the file. Don't report anything unless there is an error. Returns 1 if there was an error, and 0 otherwise.

• stats()
  Calculate statistics for the current row and column. The statistics are calculated using the fstatistic FTOOL and are returned as an array: ($sum,$mean,$sigma,$min,$max).

Special Methods

• DESTROY()
  Clean up temporary files.