This article contains the file name syntax, file structure, and usage guidelines for all FIMS-SPEAR products.

For data access, see instead Data Access. For an overview of how products produced by the FIMS team differ from products produced by the SPEAR team, see instead FIMS vs. SPEAR Features.

On this page...

Default HEALPix file structure specifications

Many FIMS-SPEAR products use the HEALPixel scheme to subdivide the sky. The following file structure properties apply to all FIMS-SPEAR HEALPix maps available at MAST, including both standard maps and hyperspectral maps. These specifications are adapted from the FITS file format specifications for HEALPix products, v0.6.0.

  • HEALPixel maps subdivide the celestial sphere into pixels of equal area, and are structured as a 1-dimensional ordered array parameterization of the 2-dimensional sky. More information about HEALPixels can be found in Hyperspectral HEALPixels.
  • The FITS primary HDU is only a header containing metadata about the observation.
  • The data are in the first and only FITS extension, in a binary table. Each row in the binary table corresponds to a HEALPixel, and each TTYPE field column corresponds to an observable being mapped (e.g., intensity).
  • The units for each TTYPEn are given in TUNITn.
  • For the intensity field, pixels without coverage by FIMS-SPEAR have null values.
  • The coordinate system for FIMS maps is Galactic, while the coordinate system for SPEAR maps is Ecliptic.
  • <Nside> = the HEALPixel resolution parameter Nside, zero-padded (e.g. "n512" for nside=512). This maps to spatial resolutions (the length along one side of a HEALPixel) as follows:

    NsideSpatial resolution
    5126.9 arcmin
    25613.7 arcmin
    12827.5 arcmin
    6455.0 arcmin
    321.8 deg
    163.7 deg
    87.3 deg

     

Additional information about hyperspectral HEALPix maps is discussed below in Hyperspectral HEALPix Maps: File Structure.


Hyperspectral HEALPix Maps

The hyperspectral HEALPix maps are all-sky images in which each pixel contains a spectrum (Figure 1). These hyperspectral maps are analogous to integral field spectroscopy or hyperspectral "cubes", except that the two on-sky spatial dimensions of the physical cube have been parameterized as a 1-dimensional ordered HEALPixel array.

All-sky imaging above, extracted spectra below.Figure 1a - FIMS hyperspectral HEALPix maps (L-Band on the left, S-band on the right), with corresponding averaged all-sky spectra in the bottom row. The Tutorials show how to perform this type of analysis.

Aquila Serpens and Aquila East image above, extracted spectra below, showing different spectra.Figure 1b - From the Tutorials, plotting a small portion of the Nside=512 FIMS hyperspectral HEALPix maps, with extracted spectra from select regions around the Aquila Rift showing that the strength of H2 lines changes with position.

The hyperspectral maps are provided with the following file naming convention:

mccm_fims-spear_<pipeline>-<slit>-<Nside>_sky-<stars>_<band>_<version>_hp-map-hsi.fits.gz

where the text outside the <brackets> is fixed, and the text inside the <brackets> changes:

  • <pipeline> = the team which produced the product, either "fims" or "spear"
  • <slit> = the slit aperture mode ("ap100" for the 100% slit mode, "ap10" for the 10% slit mode, and "apmerged" for a post-processing merge of the two). The teams recommend that users default to "ap100" products.
  • <Nside> = the HEALPixel resolution parameter Nside, zero-padded (e.g. "n512" for nside=512).

  • <stars> = stars removed ("starless") or stars not removed ("starry")
  • <band> = L band ("long") or S band ("short")
  • <version> = version number of the product in MAST, e.g v1.0 (see Updates)

Product types

_hp-map-hsi.fits.gz

HEALPix map of hyperspectral imaging

File structure

The default HEALPix file structure specifications apply to these products. However, FIMS-SPEAR hyperspectral HEALPix maps differ significantly from typical HEALPix FITS file formats due to the addition of a wavelength axis for hyperspectral imaging:

  • For TTYPE fields mapping observables with a wavelength dimension, each cell in that column of the table is itself a 1-dimensional array with a length equal to the number of wavelength bins. In schematic form, a typical binary table something like this (although different products have different columns):

    HEALPixelIntensity - BackgroundBackgroundPhoton countsExposure
    01D array (intensity spectrum)1D array (intensity spectrum)1D array (count spectrum)float (exposure time in seconds)
    11D array (intensity spectrum)1D array (intensity spectrum)1D array (count spectrum)float (exposure time in seconds)
    ...............
    LASTPIX1D array (intensity spectrum)1D array (intensity spectrum)1D array (count spectrum)float (exposure time in seconds)
  • The wavelength array is parameterized in the header extension. CRVAL1 is the wavelength of the first wavelength bin (zeroth index in Python indexing) for every spectrum, and CDELT1 is the wavelength increment per index. Both values are in units of Angstroms.

These FITS files are compressed with gzip, but as shown in the Tutorialsastropy can decompress them into memory without extracting them to disk storage.

Usage Guidelines

  • See Tutorials for detailed demonstrations of manipulating FIMS-SPEAR hyperspectral HEALPix maps. Because hyperspectral imaging (i.e., the addition of a wavelength axis) is not currently implemented in healpy or the HEALPix standards in general, these files must be opened and manipulated before feeding their data into healpy.
  • The teams recommend that users default to <slit>="ap100" products.
  • Vignetting at the high-wavelength and low-wavelength edges of the wavelength axis has been trimmed off of the FIMS hyperspectral maps, but not the SPEAR hyperspectral maps. Be careful not to casually integrate over the problematic wavelengths.
  • Caution should be exercised in interpreting data at the boundaries of sky coverage (i.e., near pixels with null values).
  • Intensities are given in continuum units (photon cm-2 s-1 sr-1 Å-1).
  • When extracting a spatially-averaged spectrum from some region, computing a simple average will in many cases lead to spiky artifacts in the averaged spectrum due to low signal-to-noise in HEALPixels with extremely low exposure time, especially at low Nside. Instead, users should strongly consider weighting the intensity by exposure time. That is, instead of calculating a simple spatial average intensity I over a number of HEALPixels N:

    $I_{\rm simple~average} = \frac{\sum_{j=1}^{N} I_{j}}{N}$,

    it may be preferred for many use cases to calculate an exposure-weighted average intensity:

    $I_{\rm weighted~average} = \frac{\sum_{j=1}^{N} I_{j} \times T_{j}}{\sum_{j=1}^{N} T_{j}}$,

    where Tj is the exposure time in HEALPixel j. This computation is demonstrated in the Tutorials. Note that by using weighting with exposure times, you are essentially giving up on a spatially uniform average in order to achieve improved signal-to-noise. If you are using an exposure-weighted average and the exact shape of the extraction region is important to your science, you should pay close attention to the exposure map in your extraction region.

  • Update 2024 Jan 10: The COUNT column is weighted by the average of flat field correction factors applied to photons in each voxel. Please contact the MAST Help Desk if you are trying to do statistical work with these data.

Integrated Emission Line HEALPix Maps

The integrated emission line maps (Integrated Maps) are all-sky images of emission lines, with special features like adaptive binning (Figure 2).

Adaptively binned C IV emission all-sky map.

Figure 2 - Map of adaptively-binned C IV emission from the SPEAR team, in Galactic coordinates, with smaller binning in regions with high flux.

The integrated emission line maps are provided with the following file naming convention:

mccm_fims-spear_<pipeline>-ap100-<binning>_sky-starless_<band>-<emission-line>_<version>_hp-map.fits

where the text outside the <brackets> is fixed, and the text inside the <brackets> changes:

  • <pipeline> = the team which produced the product, either "fims" or "spear"
  • <binning> = the spatial binning scheme, currently either "adaptive", "smoothed", or "n008" (see below)
  • <band> = L band ("long") or S band ("short") in which the emission line is located
  • <emission-line> = the emission line being integrated.

    <emission-line>SpeciesApproximate wavelength (Å)
    al-iiAl II1671

    c-ii-1037

    c-ii-1335

    C II

    1037

    1335

    c-iiiC III977
    c-ivC IV1548

    h-2


    h-2-1580

    h-2-1606

    H2

    1450-1525,1560-1630 (FIMS)

    1330-1625 (SPEAR)

    ~1580

    ~1606

    Ly-beta

    Ly β (H I)

    1026

    he-iiHe II1640
    n-iiN II1085

    o-i-1041

    o-i-1356

    o-i-1641

    O I

    1041

    1356

    1641

    o-iiiO III1666
    o-ivO IV1405
    o-viO VI1032
    si-iiSi II1533
    si-ivSi IV1394
  • <version> = version number of the product in MAST, e.g v1.0 (see Updates)

Product types

_hp-map.fitsHEALPix map

File structure

The default HEALPix file structure specifications apply to these products.

A note on <binning> schemes (which are described in greater detail at Integrated Maps):

  • <binning>="adaptive" maps are adaptively binned in the spatial dimensions; however, the underlying data structure remains a uniform-grid HEALPix map with Nside=256, in which adjacent HEALPixels that are part of the same adaptive bin simply have the same intensity value as each other.
  • <binning>="smoothed" maps are smoothed with a smoothing radius that depends on the local intensity, but the underlying data structure remains a uniform-grid HEALPix map with Nside=64.
  • <binning>="n008" are fixed-resolution maps at Nside=8

Usage Guidelines

  • All FIMS-SPEAR integrated emission line maps can be automatically read in by the python package healpyhealpy.fitsfunc.read_map(), then visualize with healpy.mollview()
  • The adaptively-binned integrated emission line maps by the SPEAR team have high spatial resolution down to 13.7 arcmin in regions with high flux, and lower spatial resolution in regions with low flux. This can be particularly useful for quickly assessing whether the spatial region you are investigating in has sufficient flux in different emission lines of interest.
  • Integrated intensities are given in line units (photon cm-2 s-1 sr-1).

Averaged Intensity HEALPix Maps

The averaged intensity maps are all-sky images of intensity averaged over all wavelengths in the given band (Figure 3).

All-sky imaging. The Milky Way is brightest, and there are variously shaped holes with no data.

Figure 3 - Nside=128 map of L-Band intensity averaged over the whole band, in Galactic coordinates, from the FIMS team.

The averaged intensity maps are provided with the following file naming convention:

mccm_fims-spear_fims-<slit>-<Nside>_sky-<stars>_<band>_<version>_hp-map.fits

where the text outside the <brackets> is fixed, and the text inside the <brackets> changes:

  • <slit> = the slit aperture mode ("ap100" for the 100% slit mode, "ap10" for the 10% slit mode, and "apmerged" for a post-processing merge of the two). The teams recommend that users default to "ap100" products.
  • <Nside> = the HEALPixel resolution parameter Nside, zero-padded (e.g. "n512" for nside=512)

  • <stars> = stars removed ("starless") or stars not removed ("starry")
  • <band> = L band ("long") or S band ("short")
  • <version> = version number of the product in MAST, e.g v1.0 (see Updates)

Product types

_hp-map.fitsHEALPix map

File structure

The default HEALPix file structure specifications apply to these products.

Usage Guidelines

  • All FIMS-SPEAR integrated intensity maps can be automatically read in by the python package healpy (healpy.fitsfunc.read_map, then visualize with healpy.mollview).
  • Caution should be exercised in interpreting data at the boundaries of sky coverage (i.e., near pixels with null values).
  • Averaged intensities are given in continuum units (photon cm-2 s-1 sr-1 Å-1).

Stellar Spectra

The stellar spectra are one-dimensional spectra of bright stars, as described in Extracting Stellar Spectra, and have the following file naming convention:

mccm_fims-spear_fims-ap100_hd<id>_long_<version>_spec.fits

where the text outside the <brackets> is fixed, and the text inside the <brackets> changes:

  • <id> = zero-padded catalog number in the Henry Draper Catalog, e.g. "hd079351" for the star HD 79351
  • <version> = version number of the product in MAST, e.g v1.0 (see Updates)

Product types

_spec.fits1D spectrum

File structure

  • The FITS primary HDU stores the spectrum, and the image FITS extension stores the uncertainties for that spectrum.
  • The wavelength array is parameterized in the headers. CRVAL1 is the wavelength of the first wavelength bin (zeroth index in Python indexing) for every spectrum, and CDELT1 is the wavelength increment per index. Both values are in units of Angstroms.

Usage Guidelines

  • The spectra can be read in using the default settings on standard software (like astropy specutils).
  • Severe vignetting is present at the high-wavelength and low-wavelength edges of each spectrum, and has not been trimmed off.

Pointed Observation Images

The SPEAR team has provided specially reduced images from pointed FIMS-SPEAR observations of the Vela supernova remnant (Nishikida et al. 2006), in which multiple back-and-forth sweeps of the spectrograph were conducted over an approximately 6x6 degree area, with a mean exposure time about 100x greater than the typical sky-survey pixel (Figure 4). As described in Vela Imaging Reduction, these images have been reduced with time-varying positional corrections.

Image of C IV emission in the Vela nebula.

Figure 4 - Map of C IV emission in the region of the Vela supernova remnant, from the SPEAR team.

The images  are provided with the following file naming convention:

mccm_fims-spear_spear-ap100_vela_<band>-<emission>_<version>_img.fits

where the text outside the <brackets> is fixed, and the text inside the <brackets> changes:

  • <band> = L band ("long") or S band ("short")
  • <emission> = the spectral feature integrated.

    <emission>LineWavelength range of multiplet
    (Angstrom)
    c-iiiC III977
    c-ivC IV1547-1552
    he-iiHe II1639-1642
    o-iiiO III1659-1668
    o-viO VI1031-1039
    si-ivSi IV1392-1404
  • <version> = version number of the product in MAST, e.g v1.0 (see Updates)

Product types

_img.fits2D image

File structure

  • In each emission line file (<emission> = an emission line), the FITS primary array is the image in line units (photon cm-2 s-1 sr-1), structured as a 2-dimensional image in which one dimension is right ascension and the other dimension is declination. The first FITS extension is the photon count image (net counts per pixel), and the second FITS extension is the exposure time map (net exposure time per pixel).
  • In each continuum image (<emission> = "continuum"), the FITS primary array is the photon count image (net counts per pixel), and the first FITS extension is the exposure time map (net exposure time per pixel).

Usage Guidelines

  • Due to the uncertain data reduction history of these files, it is recommended that they be used as a guide to the spatial morphologies of the emission lines, but not as a measurement of absolute intensity.
  • Negative values of count or intensity are artifacts of continuum subtraction or star removal, with the largest negative values appearing in stars.
  • In each Vela emission line file, the intensity image in the primary array (photon cm-2 s-1 sr-1) is equal to the photon count image in the first extension, divided by the exposure time image in the second extension, divided by the value in the keyword "GRASP" from the FITS header. That is: intensity_image = count_image / exposure_image / GRASP
  • To reduce the prevalence of low-count artifacts, pixels with exposure time-per-pixel less than 1 second have been set to null values in the intensity image (primary array). This cutoff did crop some high-count features out of the intensity image, especially for Si IV; an uncropped intensity image can be recovered by the user using the uncropped photon count and exposure time images in the extensions.
  • The Vela continuum photon count map images (<emission> = "continuum") are provided here cannot be converted to intensity in line units with the information provided. They correspond to the integrated continuum counts across the <band>.

Lower-Level Products

Sky Event Files

All-sky event files, tabulating individual photons and exposure events ("exons")—matched to orbit number, HEALPix index, and Galactic coordinates—are provided with the following file naming convention:

mccm_fims-spear_fims-<slit>-n512_sky-<stars>_<band>_<version>_<event>-evt.fits

where the text outside the <brackets> is fixed, and the text inside the <brackets> changes:

  • <slit> = the slit aperture mode ("ap100" for the 100% slit mode, "ap10" for the 10% slit mode). The teams recommend that users default to "ap100" products.
  • <stars> = stars removed ("starless") or stars not removed ("starry")
  • <band> = L band ("long") or S band ("short")
  • <version> = version number of the product in MAST, e.g v1.0 (see Updates)
  • <event> = type of event being tabulated, either photons ("phot") or exposure events ("exon")

Product types

_phot-evt.fits

_exon-evt.fits

Photon event file

Exposure event ("exon") file

File structure

  • The data are in a FITS binary table in the first extension.
  • Column descriptions and units are provided in the extension header in the TTYPE and TUNIT keywords.
    • wist_r is the percentage of photons with attitude information in each orbit. For instance, wist_r = 100 (%) means all photons had attitude information, while wist_r = 0 means no attitude information was available in that orbit at all.
  • Each row corresponds to an event (either a single photon or a single exon, depending on the file).

Usage Guidelines

  • Events are not precisely time-tagged, but rough timings can be recovered (to within a ~30 minute window) by cross-matching the orbit number in an event file to the orbit number in the Orbits File (see below).
  • These sky event files are used by the partial-pipeline code (see below) to construct the hyperspectral HEALPix maps.
  • To understand what exposure events ("exons") are, see Exposure Time Calculation.
  • Update 2024 Jan 10: The DEADFAC column is a misnomer, and it is incorrectly described in the FITS headers. It is actually a flat field correction factor averaging to 1.

Orbits Table

An orbits table provided by the FIMS team maps orbit number to a date-time window, as well as to the slit aperture mode (see Operations) and the target name. This table is available in:

mccm_fims-spear_fims_all_all_v1.0_orbits.<ext>

where the text outside the <brackets> is fixed, and the text inside the <brackets> changes:

  • <ext> = "txt" or "fits" (same content, different file structure)

Product types

_orbits.<ext>

Orbits table

File structure

  • Available as a tab-separated columns in a text file (_orbits.txt), and as a binary table extension in a FITS file (_orbits.fits).
  • Column descriptions are at the top of the text file and in the extension header of the FITS file.

Effective Area and Grasp Curves

Effective area and grasp curves (see Effective Area | Grasp) are provided with the following file naming convention:

mccm_fims-spear_<pipeline>_all_<band>_<version>_sens.<ext>

where the text outside the <brackets> is fixed, and the text inside the <brackets> changes:

  • <pipeline> = the team which produced the product, either "fims" or "spear"
  • <band> = L band ("long") or S band ("short")
  • <version> = version number of the product in MAST, e.g v1.0 (see Updates)
  • <ext> = "txt" or "fits" (see below)

Product types

_sens.<ext>

Instrument sensitivity curve (effective area, effective area fit equation, or grasp - depending on mission team and band)

File structure and usage guidance

The file structure and content varies depending on both the <pipeline> team and the <band>:

  • If <pipeline> is FIMS and <band> is S-band, two effective area (cm2) curve are available: one for orbit number 990, and one for orbit number 2429, as tab-separated columns in a text file. In the FIMS pipeline, the effective area curve at a given orbit number is obtained by linear interpolation between these two measurements.
  • If <pipeline> is FIMS and <band> is L-band, tab-separated columns "a" and "b" in a text file parameterize a linear fit to multiple measurements. The effective area (cm2) at a given orbit is obtained by calculating
    a*(orbitnumber) + b
    at each wavelength.
  • If <pipeline> is SPEAR, the grasp (effective area * field of view) curve is the 1D image in the primary HDU of a FITS file. The SPEAR team used a single grasp curve for each band, without any time-dependence.

Partial-Pipeline Code

A portion of the FIMS team IDL pipeline code, covering the conversion from sky event files to hyperspectral HEALPix maps, is provided here in a unmaintained, potentially non-runnable state without documentation, in the following tar bundle:

mccm_fims-spear_fims_sky_all_v1.0_partial-pipeline.tar

This bundle, which is stored in a tar archive, contains the following files:

  • make_datacube.pro (IDL program file): converts the sky event files to hyperspectral HEALPix maps. Also creates hyperspectral detector background maps using detback_n016.sav.
  • detback_n016.sav (IDL save file): contains the spatially-uniform detector background count (per pixel at nside=16) as a function of wavelength (10 wavelength bins, which gets interpolated to the full wavelength array in make_datacube.pro)
  • <stars>_<Nside>_<slit>.sav (IDL save files): contain the same sky event data as above (_phot-evt.fits.gz and _exon-evt.fits.gz), but included in this bundle as IDL save files in the directory structure expected by make_datacube.pro and merge_100_10.pro.
  • S and L_Aeff.orbit.calib.txt (text files): contain the same data as the _sens.txt files above, but included in this bundle with the filenames and header format expected by make_datacube.pro and merge_100_10.pro.
  • merge_100_10.pro (IDL program file): using the same inputs as make_datacube.pro, merges the aperture=100% and aperture=10% data into the aperture=merged hyperspectral HEALPix maps
  • write_hdf5.pro (IDL program file): makes a copy in HDF5 format instead of FITS (called by make_datacube.pro and merge_100_10.pro)

MAST is not able to provide user support for this pipeline code.


Unavailable Products

The following data products are not currently available and/or do not currently exist. If any of the following are on your wishlist, please let the MAST team know at mast_contrib@stsci.edu* to help MAST and the FIMS-SPEAR mission teams gauge interest in these resource-intensive projects:

  • instrument event files (Note: the provided sky event files are already highly processed and converted to sky coordinates)
  • time-tagged event files (Note: the provided sky event files match photon events to orbit number, which can currently only be cross-matched to a ~30 minute window using the orbits file)
  • raw telemetry
  • documentation / code comments for the provided FIMS partial pipeline code and detector background construction
  • pipeline code for creating the sky event files from raw telemetry
  • terrestrial aurora data

*For help with the data products that are already available at MAST, contact the Help Desk at archive@stsci.edu.

Data Use | Acknowledgements | DOI | Privacy

Send comments & corrections on this MAST document to: archive@stsci.edu