Sky Maps

This page describes data formats for data structures representing images in celestial coordinates. A sky map may have one or more non-spatial dimensions (e.g. energy or time) such that the data consists of a sequence of image planes. There are two primary pixelization formats which are described in more detail in the following sub-pages:

Both pixelization formats store the data in a single IMAGE HDU which can be either an ImageHDU or BinTableHDU depending on the image format. A BANDS HDU is required for maps with non-spatial dimensions.

BANDS HDU

For maps with non-spatial dimensions, the BANDS table defines the geometry in each band and the band to coordinate mapping for non-spatial dimensions (e.g. energy). The BANDS table is optional for maps with a single band.

The extension name of the BANDS table associated to an image HDU is given by the BANDSHDU header keyword of the image HDU. If BANDSHDU is undefined the BANDS table should be read from the EBOUNDS or ENERGIES HDU. The BANDS table extension names EBOUNDS and ENERGIES are reserved for maps with a third energy dimension and are supported for backward compatibility with existing file format conventions of the Fermi STs. Although each map will have its own IMAGE HDU, a single BANDS table can be associated to multiple maps (if they share the same geometry).

The BANDS table contains 1 row per band with columns that define the mapping of the band to the non-spatial dimensions of the map. For integral quantities (e.g. counts) this should be the lower and upper edge values of the bin. For differential quantities this should be the coordinates at which the map value was evaluated. Some examples of quantities that can be used to define bands are as follows:

  • Energy (Integral): E_MIN, E_MAX
  • Energy (Differential): ENERGY
  • Event Type: EVENT_TYPE
  • Time: TIME_MIN, TIME_MAX
  • FoV Angle: THETA_MIN, THETA_MAX

The mapping of column to non-spatial dimension is defined with the AXCOLS{IDX} header keyword. For maps with multiple non-spatial dimensions the mapping of channel number to band indices follows a column-major ordering. For instance for a map with a first energy dimension with 3 bins indexed by i and a second time dimension with 2 bins indexed by j the band index mapping to channel number k would be as follows:

(i, j) = (0,0) : (k) = (0,)
(i, j) = (1,0) : (k) = (1,)
(i, j) = (2,0) : (k) = (2,)
(i, j) = (0,1) : (k) = (3,)
(i, j) = (1,1) : (k) = (4,)
(i, j) = (2,1) : (k) = (5,)

Header Keywords

  • AXCOLS{IDX}, type: string, optional
    • Comma-separated list of columns in the BANDS table corresponding to non-spatial dimension with one-based index {IDX}. If there are two elements the columns should be interpreted as the lower and upper edges of each bin. If there is a single element the column should be interpreted as the bin center. For EBOUNDS or ENERGIES HDUs this keyword is optional.

For time based axes the additional keywords described in Formats are required.

Columns

  • CHANNEL, ndim: 1
    • Dimension: nbands
    • Unique index of the band. If this column is not defined then the band index should be inferred from the row number indexing from zero. For maps with multiple non-spatial dimensions the index mapping to channel number follows a column-major ordering.
  • E_MIN, ndim: 1, unit: keV, optional
    • Dimension: nbands
    • Lower energy bound for integral quantities.
  • E_MAX, ndim: 1, unit: keV, optional
    • Dimension: nbands
    • Upper energy bound for integral quantities.
  • ENERGY, ndim: 1, unit: keV, optional
    • Dimension: nbands
    • Energy value for differential quantities.
  • EVENT_TYPE, ndim: 1, optional
    • Dimension: nbands
    • Integer key for a sequence of independent data subselections (e.g. FRONT/BACK-converting LAT events).

WCS Columns

This section lists BANDS table columns specific to the WCS map format. These are optional columns to specify the pixelization for non-regular geometries.

  • NPIX, ndim: 2, type: int, optional
    • Number of pixels in longitude and latitude in each image plane.
  • CRPIX, ndim: 2, type: float, optional
    • Reference pixel coordinate [deg] in longitude and latitude in each image plane.
  • CDELT, ndim: 2, type: float, optional
    • Pixel size [deg] in longitude and latitude in each image plane.

HPX Columns

This section lists BANDS table columns specific to the HEALPix map format.

  • NSIDE – ndim: 1,
    • Dimension: nbands
    • NSIDE of the HEALPix pixelization in this band. If not defined then NSIDE should be inferred from the FITS header. Only required for formats that support energy-dependent pixelization (SPARSE).