|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
MAST HLSP Spectral Line List Data Delivery StandardsSummer 2013MAST 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.
[Composite Dataset Traceability] [Keyword Nomenclature] [Units] [Required Keywords] [Recommended Keywords] [Optional Keywords] [Header and Catalog Examples]
FITS File FormatsThe following list enumerates what MAST will accept in order of preference; the links provided show the mandatory keys for that extension based on the FITS Standard v3.0 (Pence et al. 2010) paper:
The FITS paper also provides a summary of the mandatory keywords for the above file types. Another option is to use non-FITS, ASCII tables to store line lists, which are also accepted by MAST. This format equates to the FITS Binary or ASCII Table Extension formats, but in straight ASCII files. More information is provided below. Lastly, we will also accept CSV format, where the first line is always the list of column names, or otherwise listed in documentation (README). FITS Standards
For multi-extension FITS files (i.e. FITS Tabular data), please note that many of the keywords cannot be in the 0th extension or HDU, they need to be within the corresponding extension(s) which contain the data.
The data format (columns) must be documented within the file itself and/or the supporting README file. For tabular, line list data in either FITS or ASCII format, a position (wavelength or frequency or wave number) and a line identifier column are required per spectral line (row). Units must be defined as header keywords and/or in the README file. All columns and rows must contain data values; blanks are not allowed. For blank values, please use value 'NaN' for numeric values or 'NULL' for strings in the ASCII file, but not both within the same column. Within a data line (row), fields should be separated by tabs, commas or the pipe ("|") character. We highly discourage the use of white space to separate fields if your data contains strings. If you must use spaces between fields, please quote your string values and provide information on how to read your data. Specification of keywords and description of the column names in the ASCII file should be done as follows:
The following is an ASCII spectra header example of keyword, value pairs, including the 4 data column descriptions for wavelength, flux, error, and data quality. Note that these map directly onto FITS header keywords so that MAST can build FITS files from ASCII tabular spectra deliveries. #TELESCOP= 'HST' / Observatory name. #INSTRUME= 'STIS' / Instrument name. #DATE-OBS= '2013-08-13T13:01:01' / Date of observation start. #EXPTIME = 444 / Effective exposure time (sec). #EXPSTART= 56518.042373 / Start time of observation (MJD). #EXPEND = 56518.048108 / End time of observation (MJD). #RADESYS = 'FK5' / Astrometric reference system. #RA_TARG = 176.42621755 / Right ascension of object (deg). #DEC_TARG= 2.82148162 / Declination of object (deg). #WAVEMIN = 4862.72 / Minimum wavelength in spectrum. #WAVEMAX = 6564.60 / Maximum wavelength in spectrum. #TARGNAME= 'HD102195' / Target name. #EQUINOX = 2000. / Equinox of the coordinates. #AIRORVAC= 'VAC' / Wavelengths in AIR or VACUUM? #BITPIX = 8 / 8-bit bytes. #NAXIS = 2 / 2-dimensional table. #NAXIS1 = 17 / Width of table in bytes. #NAXIS2 = 6 / Number of rows in table. #PCOUNT = 0 / Size of spectral data area. #GCOUNT = 1 / One data group (required keyword). #TFIELDS = 4 / Number of fields in each row. #TTYPE1 = 'WAVE' / Label for field 1. #TFORM1 = '1E' / Data format of field: 4-byte REAL #TUNIT1 = 'ANGSTROMS' / Physical unit of field. #TTYPE2 = 'NAME' / Label for field 2. #TFORM2 = '7A' / Data format of field: 1-byte CHAR #TTYPE3 = 'EW' / Label for field 3. #TFORM3 = '1E' / Data format of field: 4-byte REAL #TUNIT3 = 'ANGSTROMS' / Physical unit of field. #TTYPE4 = 'LIMIT-FLAG' / Label for field 4. #TFORM4 = '1E' / Data format of field: 2-byte INT # #COMMENT = 'Delivered to MAST from the [fill in name] HLSP project' #END Composite Dataset TraceabilityComposite data are defined as products which were constructed from other datasets. The list of original datasets from which the dataset was made can be in the README file or provided within the dataset. Please discuss these options with MAST prior to delivery. An example composite map from the PHAT HLSP project can be viewed within the PHAT catalog header where the "IM1*" through "IM5*" header keywords denote the observational details regarding the original 5 datasets that were used to create the catalog. Header Keyword Nomenclature
For example, a line list can be built from a single observation with FITS keyword 'INSTRUME' = "COS". For a composite line list made extracting line information from several sources, say COS and STIS data, the keys would be as follows:
To designate multiple keywords, we denote this as [nn]. Keyword Value Units
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.:
|
Keyword | Description |
// For Tabular FITS Data: BINARY/ ASCII TABLE EXTENSION KEYWORDS | |
SIMPLE | T / FITS standard |
XTENSION | Type of extension: FITS BINTABLE or FITS ASCII table |
EXTNAME | Extension name (single word) |
(EXTNO) | Extension number - recommended keyword |
BITPIX | number of bits that represent a data value |
NAXIS | 2 / denoting that the included data array is two-dimensional: rows and columns. |
NAXIS1 | the number of 8-bit bytes in each row of the table |
NAXIS2 | number of rows in the table |
PCOUNT | Random parameter count |
GCOUNT | Group count |
TFIELDS | Number of columns |
TBCOL[n] | [FITS ASCII table ONLY] Integer specifying the column in which field n starts (starting at 1). |
TFORM[n] | [FITS BINARY table ONLY] Format of column (valid data types) |
TTYPE[n] | Name of column (e.g. WAVE, FLUX, ERROR, DQ) |
TUNIT[n] | Column units (e.g. Angstroms, erg/s/cm^2/A, unitless) |
Keyword | Description |
// 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, see EXP* keywords below). |
EXPSTART | start time of observation, or first exposure if composite [MJD] |
EXPEND | end time of observation, or last exposure if composite [MJD] |
// PROPOSAL KEYWORDS | |
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 |
Keyword | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
// DATA DESCRIPTION KEYWORDS | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TELESCOP | observatory/facility (e.g. HST, IUE, ISO, VLT, NIST)
[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] | | | 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) | EQUINOX | Equinox of celestial coord. system | 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] | | | 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 (i.e. STIS apertures) | | | WAVEMIN | minimum wavelength n'th order | WAVEMAX | maximum wavelength n'th order | WAVEUNIT | Unit for the MINWL, MAXWL and wavelength coordinates
in the file {nm, ang, micron, mm, wavenum} | AIRORVAC | are the wavelengths in air or vacuum? One of {air, vac}. | SPECRES | spectral resolution (delta lambda) at a given
wavelength provided by WAVERES. | WAVERES | The reference wavelength of SPECRES in units of WAVEUNIT,
the resolving power "R" (often misquoted as the "resolution") would then be given as WAVERES / SPECRES. | WAVECENT | effective wavelength, or central wavelength | | | EXPDEFN | string describing how EXPTIME was calculated, i.e. 'MEAN',
when composite exposure | 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 | |
HLSP Line List, Catalog and Spectra Header 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. Please note that MAST has only had one Spectral Line List HLSP delivery to date which is listed in the examples below; the rest of the examples are to show examples data type packaging and formatting. 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 following projects contain many examples of catalog file headers, which can be used as a guideline for your datasets:
Back to general HLSP guidelines
|
|