7 Random groups structure

Although it is standard FITS, the random groups structure  has been used almost exclusively for applications in radio  interferometry; outside this field, few FITS readers can read data in random groups format. The binary table  extension (Sect. 8.3) can accommodate the structure described by random groups. While existing FITS files use the format, and it is therefore included in this standard, its use for future applications has been deprecated  since the issue of Version 1 of this standard.

   
7.1 Keywords

7.1.1 Mandatory keywords

The SIMPLE keyword  is required to be the first keyword in  the primary header of all FITS files, including those with random groups  records. If the random groups format records follow the primary header, the  card images of the primary header must use the keywords defined in Table 4 in the order   specified. No other keywords may intervene between the SIMPLE keyword and the last NAXISn keyword.

 

 

Table 4: Mandatory keywords in primary header preceding random groups.

1	SIMPLE
2	BITPIX
3	NAXIS
4	NAXIS1
5	NAXISn, n=2, ..., value of NAXIS
	(other keywords, which must include ...)
	GROUPS
	PCOUNT
	GCOUNT
last	END

The total number of bits in the random groups records exclusive of the fill described in Sect. 7.2 is given by the following  expression:

$$\mbox{\small$N_{\rm bits}$ } \vert\mbox{\small {\tt BITPIX}}\vert {\small\times} \mbox{\small {\tt GCOUNT}} {\small\times}$$

$$(\mbox{\small {\tt PCOUNT}} + \mbox{\small {\tt NAXIS2}} \times \... ...{\small {\tt NAXIS3}} {\small\times \cdots \times} \mbox{\small {\tt NAXISm}}),$$ (4)

where $N_{\rm bits}$ is  non-negative and the number of bits excluding fill, m is the value  of NAXIS, and  BITPIX, GCOUNT, PCOUNT, and  the NAXISn represent  the  values associated with those keywords.

7.1.1.1. SIMPLE keyword.

The card image containing this keyword is structured in the  same way as if a primary data array  were present (Sect. 5.4.1).

7.1.1.2. BITPIX keyword.

The card image containing this keyword is structured as prescribed in  Sect. 5.4.1.

7.1.1.3. NAXIS keyword.

The value field shall contain an integer ranging from 1 to  999, representing one more than the number of axes in each data array.

7.1.1.4. NAXIS1 keyword.

The value field shall contain the integer 0, a signature of  random groups format indicating that there is no  primary data array.

7.1.1.5. NAXISn Keywords (n = 2, ..., value of NAXIS).

The value field shall contain an integer, representing the  number of positions along axis n-1 of the data array in each group.

7.1.1.6. GROUPS keyword.

The value field shall contain the logical constant T. The  value T associated with this keyword implies that random groups records are present.

7.1.1.7. PCOUNT keyword.

The value field shall contain an integer equal to the number  of parameters  preceding each array in a group.

7.1.1.8. GCOUNT keyword.

The value field shall contain an integer equal to the  number of random groups present.

7.1.1.9. END keyword.

The card image containing this keyword is structured as described in  Sect. 5.4.1.

   
7.1.2 Reserved keywords

   
7.1.2.1. PTYPEn keywords.

The  value field shall contain a character string giving  the name of parameter  n. If the PTYPEn keywords for more than one value of n have the same associated name in the value field, then the data value for the parameter of that name is to be obtained by adding the derived data values of the corresponding parameters. This rule provides a mechanism by which a random parameter may have more precision than the accompanying data array elements; for example, by summing two 16-bit values with the first scaled relative to the other such that the sum forms a number of up to 32-bit precision.

   
7.1.2.2. PSCALn keywords.

This keyword shall be used, along  with the PZEROn keyword, when the $n{\rm th}$ FITS group parameter value  is not the true physical value , to transform the group parameter value to the true physical values it represents, using Eq. (5). The value field shall contain a floating point number representing the coefficient of the linear term in Eq. (5), the scaling factor between true values and group parameter values at zero offset. The default value for this keyword is 1.0.

   
7.1.2.3. PZEROn keywords.

This keyword shall be used, along  with the PSCALn keyword, when the nth FITS group parameter value  is not the true physical value, to transform the group parameter value to the physical value. The value field shall contain a floating point number, representing the true value corresponding to a group parameter value of zero. The default value for this keyword is 0.0. The transformation equation is as  follows:

 

$$\mbox{physical\_value} \mbox{{\tt PZEROn}} +$$

$$\mbox{{\tt PSCALn}} \times \mbox{group\_parameter\_value}.$$ (5)

   
7.2 Data sequence

Random groups data shall consist of a set of groups. The number of groups shall be specified by the GCOUNT keyword in the associated header record. Each group shall consist of the number of  parameters  specified by the PCOUNT keyword  followed by an array with the number of elements $N_{\rm elem}$ given  by the following  expression:

$$\small\mbox{$N_{\rm elem}$ } (\mbox{{\tt NAXIS2}} \times \mbox{{\tt NAXIS3}} \times \cdots \times \mbox{{\tt NAXISm}}),$$ (6)

where $N_{\rm elem}$ is the number of elements in the data array in a group, m is the value  of NAXIS, and  the NAXISn represent the values associated with those keywords.

The first parameter of the first group shall appear in the first location of the first data record. The first element of each array shall immediately follow the last parameter associated with that group. The first parameter of any subsequent group shall immediately follow the last element of the array of the previous group. The arrays shall be organized internally in the same way as an ordinary  primary data array. If the groups data do not fill the final record, the remainder of the record shall be filled  with zero values in the same way as a primary data array (Sect. 4.3.2). If random groups records are present, there shall be no primary data array.

7.3 Data representation

Permissible data representations are those listed in Sect. 6. Parameters  and elements of associated data arrays shall have the same representation. Should more precision be required for an associated parameter than for an element of a data array, the parameter shall be divided into two or more addends, represented by the same value  for the PTYPEn keyword. The value shall be the sum of the physical values , which may have been obtained  from the group parameter values  using  the PSCALn and PZEROn keywords.