spacer link to MAST page spacer logo image spacer

HLSP File Naming Convention

Names of science files must follow the naming scheme described here. This convention permits easy integration with MAST in a way that allows for automated searches. Elements of file names in black bold text, including underscores and periods, are literal text; items in blue italic text are symbolic, and are explained below. Some examples of valid filenames are given below.

hlsp_proj-id_observatory_instrument_target_opt-elem_version_product-type.extension

where the elements are:

  • hlsp - a literal string that identifies the file as a community-contributed data product.
  • proj-id - An agreed upon identifier for the HLSP collection (e.g. a project acronym). This name is also used as directory name and as a database keyword.
  • observatory - Primary observatory used to acquire the data. If multiple observatories were used, select one to be the primary in this context.
  • instrument - Instrument (and if applicable, channel) used to obtain the data (e.g. acs-wfc). When not applicable (e.g. for GALEX data), a descriptive tag like imaging or spectra will suffice.
  • target - Field name or target as designated by the team. Parts, counter numbers, and epochs are allowed in this field and should be separated by hyphens. Counters can be used when the same field is observed multiple times with same observing parameters.
    • If multiple observing epochs apply, please use the literal suffix ep followed by a number (e.g. m101-ep1, m101-ep2).
    • For parts and counters, leading zeros are required if more than one digit is needed (e.g. for 17 exposures of m101, each file has field-name as follows: m101-01, m101-02 ... m101-17; similarly, for more than 9 epochs: m101-ep01 ... m101-ep19).
    Please describe your usage of field-name parts and counters within the collection README file.
  • opt-elem - Names of optical element(s), i.e., filter or dispersing element, used to obtain the data.
    • For HST data this element should be the full filter or grating name (e.g. f606w or g230m).
    • If more than one optical element is used, separate them by hyphens (e.g. f606w-f814w).
  • version - Version designation used by the team for the HLSP delivery, such as v#.#. e.g. v2.4
  • product-type - Type of data as designated by the team (models/simulations can be indicated here). Please use a widely recognized type when possible; examples include: img, drz, sci, weight, wht, cat, theory, sim, model, map, and SED.
  • extension - Standard file format extension, e.g. .fits, .txt, or .jpg

    Compressed Data
    Appending an extension beyond the standard one, indicating the output of a common compression algorithm, is acceptable: e.g., .gz or .bz2

Other Requirements

  • Use lower-case characters only.
  • Only use underscores to delineate major fields (e.g. goods_hst).

Recommendations

  • Within fields, dashes can be used as separators (e.g. nicmos-nic3, acs-wfc, m101-01).
  • Version numbers can be specific to the project. We recommend that teams use increasing version numbers to make it easy to tell which data are superseded; MAST will NOT keep older versions of datasets unless the team explicitly requests this. Note that sometimes version numbers may denote single-EPOCH (data as in the GOODS collection); this sort of information must be documented well with deliveries.
  • We recommend that re-delivered data be given with higher version numbers (to indicate better products); we recommend that the newest deliveries contain both the re-processed data along with the single-epoch data associated with these products, if applicable.
  • All images identified using the same field-name should cover approximately the same area of the sky. If there are multiple images covering different parts of a field or source, they should have different field-names.

Example File Names

A drizzle-combined image of the GOODS field, obtained with the HST/ACS camera WFC channel using the F435W filter:

  • hlsp_goods_hst_acs-wfc_north-sect13_f435w_v2.0_drz.fits

An image of the Hubble ultra-deep field obtained with the HST/NICMOS NIC3 camera using the F110W filter:

  • hlsp_udf_hst_nicmos-nic3_treasury_f110w_v2_img.fits

A text catalog from the 47 Tuc from the DEEP47TUC survey obtained with HST/ACS, containing stellar magnitudes in the F606W and F814W filters:

  • hlsp_deep47tuc_hst_acs_47tuc_f606w-f814w_v1_catalog.txt

A 1-D extracted spectrum from the UDF/GRAPES survey (target #1), obtained with HST/ACS-WFC in slitless grism/spectroscopic mode:

  • hlsp_udf_hst_acs-wfc_g800l_id1_spc.fits

(Note that the above file name reflects the current naming scheme, rather than the name as initially delivered from the team.)