FITSTable.h
Classes
- FITSTabular -- Simplified interface to FITS tables with AIPS++ Look and Feel. (full description)
- FITSTable -- Attach a FITSTabular to a binary or ASCII table (full description)
- FITSTableWriter -- Simplified interface to create and write to a FITS Binary Table (full description)
- FITSGroupWriter -- Simplified interface to create and write to FITS random groups (full description)
Interface
- Public Members
- virtual ~FITSTabular()
- virtual Bool isValid() const = 0
- virtual const TableRecord &keywords() const = 0
- virtual const RecordDesc &description() const = 0
- virtual const Record &units() const = 0
- virtual const Record &displayFormats() const = 0
- virtual const Record &nulls() const = 0
- virtual Bool pastEnd() const = 0
- virtual void next() = 0
- virtual Bool reopen(const String&)
- virtual const String &name() const = 0
- virtual Bool hasChanged() const
- virtual void resetChangedFlag()
- virtual const Record ¤tRow() const = 0
- static TableRecord keywordsFromHDU(HeaderDataUnit &hdu, Bool allKeywords = False)
- static RecordDesc descriptionFromHDU(BinaryTableExtension &hdu)
- static Record subStringShapeFromHDU(BinaryTableExtension &hdu)
- static Record unitsFromHDU(BinaryTableExtension &hdu)
- static Record displayFormatsFromHDU(BinaryTableExtension &hdu)
- static Record nullsFromHDU(BinaryTableExtension &hdu)
- static TableDesc tableDesc(const FITSTabular &fitstabular)
Review Status
- Date Reviewed:
- yyyy/mm/dd
Prerequisite
- General knowledge of FITS binary and ASCII tables.
Etymology
Synopsis
FITSTablular is an obstract base class which is used for read-only access to
tabular FITS-like data structures.
Example
Motivation
To Do
- Eventually we'd like to be able to write the tables as well as read
them.
Member Description
virtual Bool isValid() const = 0
isValid() returns False if this object isn't a valid Tabular data
structure.
Returns keywords which are associated with the underlying FITS files.
Returns the description of the underlying FITS table.
virtual const Record &units() const = 0
Returns any TUNITnnn associated with a column (the field names
are the column names, each field value is the TUNITnnn value for
that field). Note that only those columns with a non-empty
TUNITnnn have an entry in the units() Record.
Returns any TDISPnnn associated with a column (the field names
are the column names, each field value is the TDISPnnn value for
that field). Note that only those columns with a non-empty
TDISPnnn have an entry in the displayFormats() Record.
virtual const Record &nulls() const = 0
Returns any TNULLnnn associated with a column (the field names
are the column names, each field value is the TNULLnnn value for
that field). Note that only those columns with a specific entry for
TNULLnnn and which have not been promoted to doubles due TSCAL
and TZERO values will have an entry in the nulls() Record.
The meaning of TNULL is only defined for integer and byte columns.
When a column is promoted to a double because of scaling,
any TNULL values will be assigned a value of NaN.
virtual Bool pastEnd() const = 0
Returns True if we have advanced past the end of data.
virtual void next() = 0
Advance the row if possible (guaranteed harmless if pastEnd() is True.
Reopen the table, default behavior is to do nothing, return False
virtual const String &name() const = 0
return the name
virtual Bool hasChanged() const
Has the description changed since construction, default is False
reset the changed flag, default do nothing
Return the currentRow. This is guaranteed to be valid so long as only
member functions of this base class are called (so you can safely attach
RecordFieldPtr objects to it. The result is undefined if pastEnd() is True.
Helper function for retrieving keywords from a native-FITS hdu.
If allKeywords is not True, some keywords will be excluded
from the list. Currently the list of excluded keywords
includes TTYPEnnn, TFORMnnn, and TUNITnnn
Helper function for retrieving a description from a native-FITS hdu.
Help function for retrieving any shape information from String columns
using the SubString convention.
Information is returned in a Record having named fields = all String
columns following those convention. Each of these fields is, in turn,
a sub-record having these three fields: NCHAR, NELEM, DELIM.
If NELEM == -1 then there must have been a DELIM specified and
this field is a variable shaped string array where each element has
at most NCHAR and they are separated by DELIM (which is a String field here).
Otherwise, DELIM is not used and there are NCHAR per element for each
of NELEM in each cell for this column.
Helper function for retrieving the TUNITnnn from a native-FITS hdu.
Helper function for retrieving the TDISPnnn from a native-FITS hdu.
Helper function for retrieving the TNULLnnn from a native-FITS hdu.
static TableDesc tableDesc(const FITSTabular &fitstabular)
Get a TableDesc appropriate to hold a FITSTabular
the keywords, description, units, displayFormats, and nulls are all used
Interface
- FITSTable(uInt whichHDU=1, Bool allKeywords=False)
- FITSTable(const String &fileName, uInt whichHDU=1, Bool allKeywords = False)
- ~FITSTable()
- virtual Bool eof() const
- virtual Bool reopen(const String &fileName)
- virtual const String& name() const
- virtual Bool isValid() const
- virtual const TableRecord &keywords() const
- virtual const RecordDesc &description() const
- virtual const Record &units() const
- virtual const Record &displayFormats() const
- virtual const Record &nulls() const
- virtual Bool pastEnd() const
- virtual void next()
- virtual const Record ¤tRow() const
- virtual uInt nrow() const
- virtual Int rownr() const
- virtual void move(Int torow)
- virtual const TableRecord &primaryKeywords() const
Protected Members
- Bool virtualColumns(const Vector<String>& keyNames)
Private Members
- FITSTable(const FITSTable &)
- FITSTable &operator=(const FITSTable &)
- void fill_row()
- void clear_self()
- void reopenAtFirstHDU(const String &name)
Review Status
- Date Reviewed:
- yyyy/mm/dd
Prerequisite
- General knowledge of FITS binary and ASCII tables.
Etymology
Synopsis
FITSTable is a FITSTabular which is attached to a FITS table (on disk only
presently), either Binary or ASCII.
Example
Motivation
To Do
Member Description
FITSTable(uInt whichHDU=1, Bool allKeywords=False)
this creates an invalid (isValid() return False) FITSTable
Its primary purpose is so that FITSTables can be created before
the file name is known. reopen() is then used to open the file.
FITSTable(const String &fileName, uInt whichHDU=1, Bool allKeywords = False)
0-relative HDU. It can never be zero by the FITS rules.
allKeywords is passed to FITSTabular::keywordsFromHDU
See the documentation for that function for a list of
excluded keywords when allKeywords is False.
virtual Bool eof() const
Has the end of file been reached yet
virtual Bool reopen(const String &fileName)
Attach this FITSTable to a new file name, same HDU# as at open time
virtual const String& name() const
virtual Bool isValid() const
virtual const Record &units() const
virtual const Record &nulls() const
virtual Bool pastEnd() const
virtual void next()
virtual uInt nrow() const
single FITS tables know how many rows there are
unlike general FITSTabulars, which may not know
(e.g. if it is a FITSMultiTable)
virtual Int rownr() const
these tables should also know where they are
virtual void move(Int torow)
and it should be possible to move to a desired row
the rownr() member can be used to verify that a move
was successful - this will happen if the requested row
was < rownr() or >= nrow() - i.e. movements backwards or
beyond the end of the file are not possible.
the keywords from the Primary HDU
SDFITSTable needs to make some keywords appear as
columns, this requires access to description_p, keywords_p, and
row_p. However, its not something that typical FITSTable
users will want. Therefore, I've provided this protected
function for SDFITSTable to use so as to not have to provide
direct access to those data members at the public level.
The named keywords and values are appended to the end of
row_p and removed from keywords_p, description_p is modified
appropriately. The returned value is False if any named
keyword did not appear in keywords_p (however, all named
keywords that DO appear in keywords_p will have been correctly
moved).
FITSTable(const FITSTable &)
Undefined and inaccessible. An alternative would be to use reference
semantics like Table.
FITSTable &operator=(const FITSTable &)
It is necessary to read the PDA to get the primary keywords.
If there is any data there, the FITS classes do not provide any way to
just skip over them to get to the next HDU. The only way to do that is
to actually read all of the data. If there is no data, this step is
unnecessary and so this subroutine need only be called after the primary
keywords have been read AND the PDA has some data in it. Closing the
FitsInput and reopening it is faster in most cases than reading in each
data value.
Types
- DefaultMaxStringSize = 16
-
Interface
Public Members
- FITSTableWriter(FitsOutput *file, const RecordDesc &description, const Record &maxLengths, uInt nrows, const Record &extraKeywords, const Record &units, Bool freeOutput = True, const Record &variableShapes = Record())
- ~FITSTableWriter()
- RecordInterface &row()
- void write()
- FitsOutput *writer()
- static FitsOutput *makeWriter(const String &fileName)
Private Members
- FITSTableWriter()
- FITSTableWriter(const FITSTableWriter&)
- FITSTableWriter& operator=(const FITSTableWriter&)
Review Status
- Date Reviewed:
- yyyy/mm/dd
Prerequisite
- General knowledge of FITS binary and ASCII tables.
Etymology
Synopsis
Example
Motivation
To Do
Member Description
FITSTableWriter(FitsOutput *file, const RecordDesc &description, const Record &maxLengths, uInt nrows, const Record &extraKeywords, const Record &units, Bool freeOutput = True, const Record &variableShapes = Record())
You MUST have already written a first HDU to FitsOutput.
description contains the names and types of the table columns to be written.
The row is not rearranged (i.e. they are used in order) for alignment purposes.
Array columns must have fixed shape unless tdimColumns is used. Use the
maxLengths record to indicate any string columns which should have a length other
than the default value by providing an int field of the same name as the string
field in this record.
The size of the table (nrows) must be given at creation. Use extraKeywords to
indicate any keywords not automatically created. The units record is used to
indicate the units for any column. Provide a string field with the same name as
the column field in description. If freeOutput is True, file must come from new
since it will be deleted upon destruction. You might not want this to happen if
you are going to write many tables to the same fits file. Use variableShapes to
signal which array columns have variable shape and use maxLengths to indicate
the maximum size of those variable shaped columns. The variableShapes record
should contain a String corresponding to the longest TDIM value appropriate for
each variable shaped column. The maxLengths record should contain an int field
for each variable shaped column which indicates the maximum number of elements
to be found in that column. Unused values in any cell in the variable shaped
columns will be filled with zero. These columns will use the SDFITS TDIM convention
where for column nnn there is a corresponding TDIMnnn column where
the values in each row are the true shape of the data in column nnn.
variableShapes appears as the last argument for backwards compatibility with
existing code.
RecordInterface &row()
use this to set the value of the current row to be written
Write the current row()
Don't delete this out from under us!
Returns a writer, with the first HDU filled in (set to null). The caller
is responsible for deleting the pointer returned from makeWriter.
Undefined and inaccessible
FITSTableWriter& operator=(const FITSTableWriter&)
Interface
Public Members
- FITSGroupWriter(const String &fileName, const RecordDesc &description, uInt nrows, const Record &extraKeywords, Bool freeOutput = True)
- ~FITSGroupWriter()
- RecordInterface &row()
- void write()
- FitsOutput *writer()
Private Members
- FITSGroupWriter()
- FITSGroupWriter(const FITSGroupWriter&)
- FITSGroupWriter& operator=(const FITSGroupWriter&)
- void check_error(const char *extra_info = 0)
Review Status
- Date Reviewed:
- yyyy/mm/dd
Prerequisite
- General knowledge of FITS binary and ASCII tables.
Etymology
Synopsis
Like FITSTableWriter except that this must be the first HDU and
all "columns" in the description must have the same type, i.e. float.
Example
Motivation
To Do
Member Description
FITSGroupWriter(const String &fileName, const RecordDesc &description, uInt nrows, const Record &extraKeywords, Bool freeOutput = True)
Since this must always be the first HDU, there is no point in constructing it
with a FitsOutput. description indicates the names of the random groups parameters.
nrows is a synonym for ngroups. Use extraKeywords to
indicate any keywords not automatically created (SIMPLE, BITPIX, NAXIS*, EXTEND,
BLOCKED, GROUPS, PCOUNT, GOUNT, ORIGIN, END). If freeOutput is True, file will be
deleted by the destructor. You might not want this to happen if
you are going to write any extensions to the same fits file. You can get the
FitsOutput used here from write()
RecordInterface &row()
Set the values for the current group
Write the current group (row()).
Don't delete this out from under us!
Undefined and inaccessible
FITSGroupWriter& operator=(const FITSGroupWriter&)
void check_error(const char *extra_info = 0)
Checks error status of writer_p and group_p. Cleans up and throws an exception if bad.