Difference between revisions of "Notes for Labelling FITS files"

From The SBN Wiki
Jump to navigation Jump to search
(Safety Save)
(Safety Save)
Line 83: Line 83:
 
! FITS !! PDS4 ''Field_Binary''
 
! FITS !! PDS4 ''Field_Binary''
 
|-
 
|-
| align="center" | TFORM || <data_type>
+
| TTYPE || <name>
 
|-
 
|-
| align="center" | TTYPE || <name>
+
| TUNIT || <unit>
 
|-
 
|-
| halign="left" | TUNIT || <unit>
+
| TSCAL || <scaling_factor>
 
|-
 
|-
| align="center" | TSCAL || <scaling_factor>
+
| TZERO || <value_offset>
 
|-
 
|-
| align="center" | TZERO || <value_offset>
+
| TNULL <br> ''integer data only'' || ''see below''
 
|-
 
|-
| align="center" | TNULL <br> ''integer data only'' || ''see below''
+
| TDISP || ''see below''
 
|-
 
|-
| align="center" | TDISP || ''see below''
+
| TFORM || &lt;data_type&gt; <br> ''see below''
 
|}
 
|}
 +
 +
 +
''TNULL'' is only properly used for integer data.  It indicates a null data flag, and corresponds to the value found in the file - before scaling of offset are applied.
 +
 +
 +
''TDISP'' provides a recommended print format for the binary data, using a limited set of FORTRAN-like specifiers.  In PDS4 the specifiers follow the POSIX standard and are described on the [[PDS4_field_format_Conventions]] page.
 +
  
 
TFORM will have to be translated to the PDS4 equivalent. The FITS ''BINTAB'' scalar types that are directly supported by PDS4 binary tables are:
 
TFORM will have to be translated to the PDS4 equivalent. The FITS ''BINTAB'' scalar types that are directly supported by PDS4 binary tables are:
  
 
{| class="wikitable"
 
{| class="wikitable"
| FITS Type Letter || PDS4 ''&lt;data_type&gt;''
+
! FITS Type Letter !! PDS4 ''&lt;data_type&gt;''
 
|-
 
|-
| B
+
| align="center" | B || SignedByte
 
|-
 
|-
| I
+
| align="center" | I || UnsignedMSB2
 
|-
 
|-
| J
+
| align="center" | J || UnsignedMSB4
 
|-
 
|-
| K
+
| align="center" | K || UnsignedMSB8
 
|-
 
|-
| A
+
| align="center" | A || ASCII_String <br> (''or any other appropriate ''ASCII_*'' type'')
 
|-
 
|-
| E
+
| align="center" | E || IEEE754MSBSingle
 
|-
 
|-
| D
+
| align="center" | D || IEEE754MSBDouble
 
|}
 
|}
  
 +
In addition to these types, the FITS standard allows a field to contain a complex number, a repeating value (basically, a vector), or an array descriptor.  In PDS4, complex types are not directly supported.  Simple repeating values (vectors) can be represented using a ''&lt;Group_Field_Binary&gt;''.  Arrays probably can as well, but the method has not yet been defined.  So if your FITS binary table contains complex values and array descriptors, contact your PDS consultant ASAP for additional instructions.
  
In addition, there are complex types, array descriptors, and the option to have a field containing a repeating value (basically, a vector).  In PDS4, complex types are not directly supported.  Simple repeating values (vectors) can be represented using a ''&lt;Group_Field_Binary&gt;''.  Arrays probably can as well, but the method has not yet been defined.  So if your FITS binary table contains complex values and array descriptors, contact your PDS consultant ASAP for additional instructions.
 
  
According to the FITS standard, ''TNULL'' should only be used for integer data.  It indicate a null data flag, and corresponds to the value found in the file - before scaling of offset are applied.
+
Finally, the ''TFIELDS'' keyword in the ''BINTAB'' extension corresponds to the ''&lt;fields&gt;'' attribute in the ''&lt;Record_Binary&gt;'' class.
  
''TDISP'' provides a recommended print format for the binary data, using a limited set of FORTRAN-like specifiers.  In PDS4 the specifiers follow the POSIX standard and are described on the [[PDS4_field_format_Conventions]] page.  Note, though, that if you have a repeating field
 
  
TFIELDS
+
{| class="wikitable" style="background-color: yellow"
 +
| '''''Note:''''' ''This will likely change in subsequent versions of the Information Model, to include both a &lt;fields&gt; and a &lt;group_fields&gt; count, the sum of which may or may not be equal to ''TFIELDS'', depending on the presence of array descriptors in the ''BINTAB'' record.
 +
|}
  
 
== ASCII Tables ==
 
== ASCII Tables ==

Revision as of 20:23, 28 February 2013

Fits tables, images and arrays are all compliant as they are with the PDS4 data formatting standards. Follow the guidelines below for filling in the PDS4 attribute values.

Scalar Data Types

Regardless of the data structure, the supported data types are strictly limited by the FITS standard. Here are the types you may encounter in FITS files (as specified by the BITPIX keyword), and their PDS4 equivalents:

BITPIX Value PDS Data Type(s)
8 UnsignedByte -or- 7-bit ASCII character
16 SignedMSB2 (integer)
32 SignedMSB4 (integer)
-32 IEEE754MSBSingle (float)
64 SignedMSB8 (integer)
-64 IEEE754MSBDouble (float)

Table types will always have "BITPIX = 8". Binary tables will have data types for each individual field (all corresponding to one of the types above) indicated by the TFORM keywords. ASCII tables are restricted to 7-bit ASCII printable characters + carriage-control, and the individual fields will have types corresponding to the various ASCII_* data types of PDS4.

Headers

Use the PDS4 Header object to describe any type of FITS header.

  • For <encoding_type>, use "Character"
  • For <external_standard_id>, use "FITS 3.0". This is not a valid standard value, but the current value is not sufficiently specific. If you want to reference an earlier version of the FITS standard, check with your PDS consultant.
  • The <object_length> must be the number of FITS blocks comprising the header * 2880 (the size of a single FITS block).

Arrays

Axis Ordering

Fits array data are are stored such that the NAXIS1 subscript varies fastest, NAXIS2 next fastest, and so on up to NAXISn. So the storage order is first-index-fastest in FITS notation.

In PDS, arrays are stored so that axis 1 (the axis described by the <Axis_Array> that has <sequence_number> of "1") varies least rapidly, axis 2 next least rapidly, and so on to axis n.

So, when labeling a FITS array as a PDS Array-type object, the highest-numbered NAXIS* becomes axis 1 in the PDS array, the next-highest NAXIS* becomes axis 2, and so on.

Array Elements Description

In the FITS primary data header or image extension header, the following reserved FITS keywords also have direct PDS4 equivalents in the <Element_Array> class.

FITS PDS4 Array
BSCALE <Element_Array>/<scaling_factor>
BZERO <Element_Array>/<value_offset>
BUNIT <Element_Array>/<unit>
BLANK
integer data only
see below
DATAMAX <Object_Statistics>/<derived_maximum>
DATAMIN <Object_Statistics>/<derived_minimum>

The BLANK keyword, when used according to the FITS standard, may only be used with integer data, and may either be a blank (if BSCALE is 1 and BZERO is 0), otherwise it contains a flag value indicating null data. If you need to specify a null value, add the <Special_Constants> class to the Array class, and select the appropriate special constant for the case in hand. Note that the BLANK value is the value read from the file - before any scale factor and offset are applied.

2D Images

In addition to the above correspondences, the PDS4 Array_2D_Image class has the following additional correspondences.

  • NAXIS1 corresponds to axis 2, and axis 2 must have an <axis_name> of "Sample".
  • NAXIS2 corresponds to axis 1, and axis 1 must have an <axis_name> of "Line".

Also note that the FITS standard says nothing about display direction. It seems to be universally true that samples (NAXIS1) are always drawn left-to-right; but lines are drawn either top-to-bottom or bottom-to-top with roughly equal frequency. You will have to look at your FITS images and determine the correct order of display.

The display order is specified in the <Display_2D_Image> class.

Binary Tables

In the FITS BINTAB extension, the column description keywords, for the most part, translate directly to PDS4 Field_Binary class attributes:

FITS PDS4 Field_Binary
TTYPE <name>
TUNIT <unit>
TSCAL <scaling_factor>
TZERO <value_offset>
TNULL
integer data only
see below
TDISP see below
TFORM <data_type>
see below


TNULL is only properly used for integer data. It indicates a null data flag, and corresponds to the value found in the file - before scaling of offset are applied.


TDISP provides a recommended print format for the binary data, using a limited set of FORTRAN-like specifiers. In PDS4 the specifiers follow the POSIX standard and are described on the PDS4_field_format_Conventions page.


TFORM will have to be translated to the PDS4 equivalent. The FITS BINTAB scalar types that are directly supported by PDS4 binary tables are:

FITS Type Letter PDS4 <data_type>
B SignedByte
I UnsignedMSB2
J UnsignedMSB4
K UnsignedMSB8
A ASCII_String
(or any other appropriate ASCII_* type)
E IEEE754MSBSingle
D IEEE754MSBDouble

In addition to these types, the FITS standard allows a field to contain a complex number, a repeating value (basically, a vector), or an array descriptor. In PDS4, complex types are not directly supported. Simple repeating values (vectors) can be represented using a <Group_Field_Binary>. Arrays probably can as well, but the method has not yet been defined. So if your FITS binary table contains complex values and array descriptors, contact your PDS consultant ASAP for additional instructions.


Finally, the TFIELDS keyword in the BINTAB extension corresponds to the <fields> attribute in the <Record_Binary> class.


Note: This will likely change in subsequent versions of the Information Model, to include both a <fields> and a <group_fields> count, the sum of which may or may not be equal to TFIELDS, depending on the presence of array descriptors in the BINTAB record.

ASCII Tables