NOTE: Most of the High Level Science Products are unavailable while unscheduled maintenance is being performed. They will be incrementally restored over the course of this week. We apologize for any inconvenience.
MAST HLSP Image Data Delivery Standards and FITS Keyword Information
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.
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 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".
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:
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
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.:
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.:
|// DATA DESCRIPTION KEYWORDS|
|TELESCOP|| observatory (e.g. HST, IUE, ISO, VLT)
[Expand TELESCOP values 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 and time of observation start in the ISO
standard 8601 format: YYYY-MM-DDThh:mm:ss.sss; start of first observation if composite||Alternative, accepted date format
(yyyy-mm-dd); must be paired with 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)|
|TARGNAME||target name (according to raw data or catalog)|
|RA_TARG||right ascension of the target [deg] (J2000)|
|DEC_TARG||declination 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|
|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|
|BUNIT||flux unit of DATAMIN and DATAMAX|
|RESUNIT||spatial resolution units|
|WAVEUNIT||central wavelength units|
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: