spacer link to MAST page spacer logo image spacer
 
link to STScI page


MAST HLSP Image Data Delivery Standards and FITS Keyword Information

Spring 2013

This page describes FITS image data standards for HLSP deliveries. Also please read the general HLSP guidelines page. FITS keywords fall into three categories: required, recommended and optional. more | less

We have tried to generalize the FITS keywords requirements across a number of image types, therefore some of these keywords may not be applicable to your data. We suggest you consult a MAST staff member prior to delivery, to be sure your data abides by the FITS and MAST delivery standards.

MAST has put together the following information because it is essential for data deliveries. If the archive cannot extract the information they need from dataset headers, MAST will attempt to calculate it based on original exposures when possible. If MAST is not able to extract or calculate what it needs based on the delivered dataset headers, then some of the data will not be searchable and will not be displayed across multi-mission search results.

[General Header Information]   [FITS Standards]   [Composite vs Single Image]  

[Exposure Time Map]   [Multiple Filters]   [Keyword Nomenclature]   [Units]   [Required Keywords]  

[Recommended Keywords]  [Optional Keywords]  [Header Examples

General Header Information

MAST requires that FITS headers contain the following information (see Required keywords below):
  • Relevant ID information (program ID, proposal ID, PI name, etc) if appropriate
  • Time coverage (observation start and duration)
  • List of exposures (origin of mosaics, only needed for MAST Missions)
  • Pointing location and World Coordinate System (WCS)
  • Wavelength coverage

FITS Standards

The above requirements translate into FITS header keywords below. These keywords and files themselves must abide by the FITS standard, and therefore cannot have errors when being checked by tools like 'fverify' or 'fitsverify'. more | less

Composite vs Single Image

Composite data deliveries of MAST Missions are required to contain a list of the original datasets from which the mosaic was made. more | less

Composite data are defined as images which were constructed from other images. The most common examples of composite data are highly processed science products made from other images, as well as mosaic images. We accept images as either single, large mosaics and/or broken up into smaller sections/fields, depending on the specific needs of the project.

The list of original datasets from which the dataset was made can be a FITS table as a separate HDU in the composite dataset, or an ASCII list of exposure names (e.g. IPPPSSOOT convention for HST, tile names for GOODS CDF-S field, per composite dataset). An example composite map from the CLASH HLSP project can be viewed here where the 2nd column is the ipppssoot name for HST; for other missions, the data ID is required, see example for the FUSE Magellanic Cloud HLSP project.

Exposure Time Maps

Composite data deliveries are encouraged to contain exposure time maps. These can more accurately denote the exposure time across a composite image than simply using header keywords. We suggest exposure time maps have file name extensions "_exp.fits".

Multiple Filters

We recommend that images from different filters that have the same field-name should have matching sizes and WCS coordinates. All images identified using the same field-name should cover the same part of the sky. If there are multiple images covering different parts of an object, they should have different field-names. This will be helpful to MAST for making color previews and displaying color images.

Header Keyword Nomenclature

For single images, the keyword will contain a value; if the image is a composite, that keyword can contain the value of "MULTI", followed by a list of N similar keywords which encompass all the values needed to explain the composite data using a series of related keywords. more | less

For example, the single image can have FITS keyword 'FILTER' = "g". For a composite image made of UBV exposures, the keys would be as follows:

  • FILTER = "MULTI"
  • FILTER01 = "U"
  • FILTER02 = "B"
  • FILTER03 = "V"

To designate multiple keywords, we denote this as [nn].

Keyword Value Units

Some keywords have standard units and do not need to be explicitly specified in the headers. In cases where you need to specify units for header keywords, this can be done in one of two ways: more | less

  1. KEYWORD + KEYWORD_UNIT pair
  2. You can specify the keyword units using a second, similar keyword where the keyword name contains the string "_UNIT" or "UNIT". Please remember to stay within the FITS 8-character keyword name limit. E.g.:

    WAVECENT = 1688 / central wavelength
    WAVEUNIT = angstrom / central wavelength units

  3. KEYWORD = value / [unit] in brackets within the FITS comment
  4. Comments can contain the keyword unit within brackets; this should be the first text following the standard fits comment delimiter "/", the single slash. Please remember to stay within the FITS 80-character line length limit, which includes the comments. E.g.:

    RA_TARG = 2.0952854139 / [deg] right ascension of target

Back to top


REQUIRED FITS HEADER KEYWORDS


KeywordDescription
  
             // DATA DESCRIPTION KEYWORDS
TELESCOP observatory (e.g. HST, IUE, ISO, VLT) [Expand TELESCOP values List | Retract/Close List]

INSTRUME single instrument alone, or instrument/detector names, or instrument/detector-subdetector names (e.g. "WFPC2" or "ACS/WFC" or "ISOCAM" or "STIS/FUV-MAMA") or "MULTI" for composite [View Current List]
INSTRU[nn] if INSTRUME="MULTI", then an element from allowed values of INSTRUME [View Current List]
FILTER filter for single exposure or "MULTI" for composite exposure [View Current List]
FILTER[nn] if FILTER="MULTI", filters list when composite exposure [View Current List]
  
             // DATE AND TIME KEYWORDS
DATE-OBS date and time of observation start in the ISO standard 8601 format: YYYY-MM-DDThh:mm:ss.sss; start of first observation if composite
(DATE-OBS) Alternative, accepted date format (yyyy-mm-dd); must be paired with TIME-OBS
(TIME-OBS) Alternative, accepted time format (hh:mm:ss); must be paired with DATE-OBS (yyyy-mm-dd)
EXPTIME effective exposure time (seconds) for single exposure, or "1" for composite (which are typically in units of counts/second) [composite exptime-related keywords] [exp map]
EXPSTART start time of observation, or first exposure if composite [MJD]
EXPEND end time of observation, or last exposure if composite [MJD]
  
             // WORLD COORDINATE SYSTEM (WCS) KEYWORDS
SIMPLE T / FITS standard
BITPIX number of bits that represent a data value
RADESYS astrometric reference system (e.g. FK5, ICRS, FK4, ECL, GAL, SGAL)
NAXIS number of data axes
BITPIX number of bits that represent a data value
NAXIS[n] number of points on axis [n]
CRPIX[n] pixel at axis origin
CRVAL[n] value at axis origin
CD[n]_[n] image coordinate matrix; mandatory terms 1_1, 1_2, 2_1 and 2_2
CTYPE[n] description of axis (array)

Back to top


RECOMMENDED FITS HEADER KEYWORDS


KeywordDescription
  
TARGNAMEtarget name (according to raw data or catalog)
RA_TARGright ascension of the target [deg] (J2000)
DEC_TARGdeclination of the target [deg] (J2000)
EPOCH Epoch of the observation (considered as deprecated; use EQUINOX when possible)
  
PROPOSID Proposal ID (when available)
HLSPLEAD Full name of the lead of HLSP project (Firstname M. Lastname)
PR_INV_L Last name of principal investigator
PR_INV_F First name of principal investigator
PR_INV_M Middle name or initial of principal investigator

Back to top


OPTIONAL FITS HEADER KEYWORDS


KeywordDescription
  
HLSPNAME High Level Science Product (HLSP) project name, long form
HLSPACRN High Level Science Product (HLSP) project acronym, short form
CITATION citation reference of this project, for publications (else in HLSP README file)
DETECTOR detector of the instrument (same order as INTRUME) or "MULTI" for composite exposure
DETECT[nn] list of detectors of the instrument of composite exposure
APERTURE for HST, the name of the aperture of the instrument (STIS apertures)
  
EXPDEFN string describing how EXPTIME was calculated, i.e. 'MEAN', when composite exposure [exp map]
EXPMIN if EXPDEFN='MIN', numerical value = minimum composite exposure
EXPMAX if EXPDEFN='MAX', numerical value = maximum composite exposure
EXPMODE if EXPDEFN='MODE',numerical value = mode of composite exposure
EXPMED if EXPDEFN='MED', numerical value = median of composite exposure
EXPMEAN if EXPDEFN='MEAN', numerical value = mean of composite exposure
EXPSUM if EXPDEFN='SUM',numerical value = sum of composite exposure
  
DATAMIN minimum flux
DATAMAX maximum flux
BUNIT flux unit of DATAMIN and DATAMAX
RESOLUTI spatial resolution
RESUNIT spatial resolution units
WAVECENT central wavelength
WAVEUNIT central wavelength units
  

Back to top


HLSP Image Header Examples

Expand for Examples | Retract/Close Examples

MAST has been ingesting and distributing HLSP data products for over 10 years. During this period, the requirements for HLSP data deliveries have expanded in order to help unify all datasets housed at MAST for ease of multi-mission searching. The example HLSP headers may not abide by all the requirements listed above because they were delivered prior to some requirements being written. We encourage the data delivery teams to provide data sample so that all header and data issues can be worked out prior to the actual delivery for ingestion into the archive.

The CLASH and CANDELS can be considered complex examples of HLSP projects. The HIPPIES dataset can be considered more simple example of an HLSP project. These projects contain many examples of image file headers, which can be used as a guideline for your datasets:

Back to general HLSP guidelines

Back to top