Data Model: The Facility Infrared Spectropolarimeter
Instrument Description
The FIRS instrument is a high-resolution infrared spectropolarimeter active at the Dunn Solar Telescope. The instrument has historically had several configurations, however, under consortium setup, it is configured for detailed spectropolarimetry of the Si-I/He-I line complex around 10830Å. An image of the field and slit is typically taken simultaneously, however, data from the slit0jaw imager is not typically reduced, and should only be used as fiducials for the purposes of instrumental alignment in the case where too little structure is present in the field rasters taken by the FIRS instrument. Typically, the FIRS data product can be adequately aligned without use of the slit-jaw imaging files.
While the specific configuration of the FIRS instrument is variable, the following parameters represent a "typical" instrumental configuration under consortium operations.
| Parameter | Typical Value | Comments |
|---|---|---|
| Camera | Virgo 1k | 1024x1024 infrared camera, nitrogen-cooled |
| Spectral Range | 10819--10858Å | In typical consortium operating mode |
| Grating | 31.6 line/mm, 63.5° | He I operates at the 52nd order |
| Slit Width | 40 micron | 0.3 arcsec |
| Plate Scale | 0.15 arcsec/pixel | 0.038Å/pix |
| Maximum Field Size | 165x75 arcsec | Corresponds to a 550-step field |
| Polarization Sensitivity | <0.1% | Assuming 10 coadds |
| Time per step | ~13sec | 10 coadds, 125ms/exp |
Data File Description & Summary
Level-0 General Description
The FIRS instrument outputs level-0 files in FITS format, though the filetypes are not tagged as FITS, and do not have a file extension. Each file corresponds to a single exposure series. This can be a single slit position in the case of maps, a single dark frame, or, in the case of the polarization calibration files, a single rotation state of the DST Port-4 Retardance Unit. Each FITS file has a filename of the form "firs.2.YYYYMMDD.HHMMSS.NNNN.0000" where the 2 refers to the infrared arm of the instrument, YYYYMMDD is the date, HHMMSS is the time of the series start, NNNN is the number of the exposure in the seires, and 0000 is appended to all files.
Each file contains a single header and a single data extension. The file type (e.g., flat, dark, field scan, etc.) is contained in the "COMMENT" FITS Header keyword. Each data extension has the shape (8, 1024, 1024), with a different image formed at each of the 8 states of the Liquid Crystal Variable Retarders (LCVRs) that give the instrument its polarization capabilities.
PRIMARY HEADER DESCRIPTION
For the sake of brevity, a concept I heard of once but have yet to internalize, base FITS Header keywords (NAXIS, BITPIX, etc.) are omitted.
| Key | Value (Ex.) | Comment |
|---|---|---|
| DATE_OBS | YYYY/MM/DD | Date only |
| TIME_OBS | HH:MM:SS | Time only |
| OBS_STAR | YYYY-MM-DDTHH:MM:SS.FFF | UTC Start time |
| OBS_END | YYYY-MM-DDTHH:MM:SS.FFF | May not increment correctly, and may be the same as OBS_STAR |
| EXP_TIME | 123 | MSec exposure time |
| SUMS | 10 | Co-adds (number of images summed, higher=better signal in Q, U, V) |
| LCVR0/1 0-7 | 1.23400 | For both LCVRs, voltage settings for each of the 8 modulation states in mV. 18 keys total |
| INST_ID | FIRS.2 | FIRS.1 was the visible arm of the spectropolarimeter |
| WAVELENG | 10830A | |
| CAMERA | SEIR1K | The IR camera is a Seir Virgo 1k. My documentation on it is spotty |
| NO. LOOP | 300 | Number of exposure sets (slit positions) in series |
| LOOP | 0 | Which set the instrument is on |
| NOREPEAT | 1 | 1 repeat is a single scan |
| REPEAT | 0 | Current repeat step |
| SLITWIDTH | 0.0400000 | Operator-set, slit width in mm. Can be manually set higher to "trick" the instrument into taking coarser rasters. |
| FEED F/# | F/36 | Final focal ratio at the camera |
| FSM X0 | -1.234 | Field scan mirror start position (mm) |
| FSM DX | 0.0036 | Calculated from slit width, mm |
| FSM CP | 0.123 | Current position of field scan mirror, mm |
| DST_TIME | YYYY-MM-DDTHH:MM:SS.FFF | NOT the current time, most recent time the DST master clock was updated |
| DST_AZ | 1.234E+01 | Turret steering mirror system azimuth (deg) |
| DST_EL | 1.234E+00 | Turret steering mirror system elevation (deg). NOTE: Do NOT use these for pointing information. Approximate only |
| DST_TBL | 1.234E+02 | Angle of DST observing room table (deg). Not directly linked to Solar-North |
| DST_GDRAN | 1.33E+01 | A guider angle of 13.3 degrees corresponds to a North/South orientation of the FIRS slit. Why 13.3? It was changed from 0 in the 80s to accomodate an instrument that is no longer around |
| DST_XGDR | 1.234E+02 | Guider head position in arcsec. NOT the same as Solar-X/Y |
| DST_YGDR | 1.234E+01 | |
| DST_SLAT | 1.234E+00 | Stonyhurst Latitude (deg). Accurate to a few arcsec |
| DST_SLNG | 1.234E+00 | Stonyhurst Longitude (deg). |
| DST_HPA | 1.234E+01 | Heliocentric position angle (degrees) |
| DST_GPA | 1.234E+02 | Geocentric position angle (degrees) |
| DST_RV | 5.396E-01 | Heliocentric radius vector |
| DST_PEE | 1.234E+01 | Solar P Angle (degrees, unfortunate keyword) |
| DST_BEE0 | 1.234E+00 | Solar B0 angle (degrees) |
| DST_ELL0 | 1.234E+02 | Solar L0 Angle (degrees) |
| DST_SDIM | 1.234E+03 | Solar diameter (arcsec) |
| DST_SEE | 1.234E-01 | Seykora scintillation monitor value (arcsec) |
| DST_SAZ | 1.234E+02 | Solar azimuth (degrees) |
| COMMENT | scan, sflt, dark, pcal, lgrd, phol, targ, lflt, othr | Science data, solar flat, dark frame, polcal frame, line grid, alignment pinhole, AF target, lamp flat, other |
Level-1/1.5 Description
Integration of the FIRS Level-1 pipeline into the SSOSoft platform is ongoing. Currently, the Level-1 pipeline is a robust IDL-based solution written by Dr. Christian Beck. It corrects the data for dark current, flat field, and performs a polarization calibration, correcting for the Mueller matrix of the telescope/optical system, as well as I→Q,U,V crosstalk. The polarization calibration is performed with known values of the DST base telescope optical systems (entrance window to observing room floor) and Port 4 Calibration Unit. These values were last updated in 2011 via interferometry, and monitoring since then has not shown a need to update them.
The IDL pipeline produces as its final product two files for every field scan reduced, a ".dat" binary file containing the reduced datacube, and a ".sav" IDL save file containing the information required to read and manipulate the binary file. The "firs-tools" routines available here contain a "read_firs" function that will read the file into a python session. The function takes one argument, the path to the ".dat" file, and assumes that the ".sav" file is in the same folder. Both files are required.
As of 2023, a level-1.5 pipeline has been developed for the FIRS instrument that corrects for several known effects, and repackages the data as FITS with these additional corrections applied. The Level-1.5 Pipeline has not been tested on legacy FIRS data, and is not guaranteed to work with multi-slit data, or data other than He I 10830Å. It likely can be applied with only minimal tweaking, but is not guaranteed. The current iteration of the pipeline (Jan. 2024) performs the following functions:
- Correction for prefilter curvature
- De-fringing of Q, U, and V data
- Wavelength calibration
- Correction for linear tilt of Q, U, V data
- Correction for V→Q, U crosstalk
In order to perform the fringe correction, the Level-1.5 pipeline currently requires a solar flat field map that has been processed by the IDL pipeline as a science map. FIRS fringes are (mostly) time-invariant. Typically, these could be removed during flat fielding, however, solar observations necessitate the Sun be used as a flat field, with spectral lines iteratively removed from the flat. Unfortunately, this process also tends to remove fringe patterns. As a workaround, the flat field is used in the Level-1.5 pipeline to create a finge template via Fourier analysis, which can be removed from the Q, U, and V data. Flat data is used to minimize "real" polarization signals. The correction is automated, and works best at the shorter wavelengths, coincidentally around the Si I/He I complex.
V→Q, U crosstalk corrections are estimated by analyzing structural differences in the polarization signals. Magnetically active regions have different structures in V, Q, and U. The crosstalks values from V can be determined iteratively by finding the value that results in the most distinct structures between V, Q, and U. In regions near the limb, or without strong photospheric magnetic field configurations, the crosstalk value defaults to 0.
The Level-1.5 File
The Level-1.5 FITS file product was designed to be similar to the IRIS Level-3 data product, containing the entire raster data cube in a single file along with wavelength and timing information. The Level-1.5 product contains the following extensions:
| FITS Index | Extension Name (EXTNAME) | Number of dimensions | Description |
|---|---|---|---|
| 0 | N/A | 0 | Header only, contains information about the contents of the FITS file |
| 1 | Stokes-I | 3 | Stokes-I datacube NAXIS1 is spectral, 2 is the x-direction (slit position), 3 is the y-direction (position along slit). In python this is (ny, nx, nlambda) |
| 2 | Stokes-Q | 3 | Stokes-Q datacube of the same shape as the Stokes-I datacube |
| 3 | Stokes-U | 3 | Stokes-U datacube of the same shape as the Stokes-I datacube |
| 4 | Stokes-V | 3 | Stokes-V datacube of the same shape as the Stokes-I datacube. Q,U,V are NOT normalized, and shoud be divided by I for most inversion codes and analyses |
| 5 | lambda-coordinate | 1 | Wavelength array as determined by the Level-1.5 pipeline. |
| 6 | time-coordinate | 1 | Time of each exposure start, given in seconds from 00:00 UTC from the observing day |
Level-1.5 Header
The following are examples of the FITS header objects associated with Level-1.5 files. As Stokes I, Q, U, and V extensions are practically identical, only one header example is given for extension indices 1 through 4.
EXTENSION 0: General Information
| Key | Value (Ex.) | Comment |
|---|---|---|
| DATE | YYYY-MM-DDTHH:MM:SS | File creation date |
| TELESCOP | DST | |
| INSTRUME | FIRS | |
| DATA_LEV | 1.5 | |
| DATE_OBS, STARTOBS | YYYY-MM-DDTHH:MM:SS.FFFF | Both keys are present |
| DATE_END, ENDOBS | YYYY-MM-DDTHH:MM:SS.FFFF | Again, both are present |
| BTYPE | Intensity | |
| BUNIT | Corrected DN | |
| FOVX | XX.X | Approximate FOV in the X (slit step) direction |
| FOVY | 75.15 | FOV in the y (along slit) direction. Should always be near 75. |
| XCEN | 123.456 | Solar-X, Arcsec, center of FOV |
| YCEN | 123.456 | Solar-Y, Arcsec, center of FOV |
| ROT | 123.456 | Rotation from Solar-North. All Level-1.5 files should be translated such that the y-axis aligns with this angle |
| EXPTIME | 125 | Single-exposure time, ms |
| XPOSUR | 1250 | Cumulative exposure time, single*coadds, ms |
| NSUMEXP | 10 | Number of coadds |
| PRSTEP1, 2, 3, 4 | CORRECTION NAME | List of calibrations performed |
EXTENSION 1--4, Stokes Vector Data
| Key | Value (Ex.) | Comment |
|---|---|---|
| EXTNAME | Stokes-I/Q/U/V | |
| CDELT1 | 0.3 | Slit step size |
| CDELT2 | 0.15 | Plate scale in slit-direction |
| CDELT3 | 0.038 | Plate scale in wavlength-direction |
| CTYPE1 | HPLN-TAN | Solar-X for those of you at home |
| CTYPE2 | HPLT-TAN | Solar-Y |
| CTYPE3 | WAVE | Wavelength |
| CUNIT1/2/3 | arcsec/arcsec/Angstrom | |
| CRVAL1 | XXX.XXXX | Center Solar-X |
| CRVAL2 | YYY.YYYY | Center Solar-Y |
| CRVAL3 | LLLLL.LLLLL | Wavelength start value |
| CRPIX1/2/3 | XXX/YYY/1 | By convention, spatial axes are referenced in the middle, wavelength is referenced at the first entry |
| CROTAN | AAA.AAAAA | Angle from solar north |
EXTENSION 5: Wavelength Axis
| Key | Value (Ex.) | Comment |
|---|---|---|
| EXTNAME | lambda-coordinate | |
| BTYPE | lambda axis | |
| BUNIT | [AA] |
EXTENSION 6: Time Axis
| Key | Value (Ex.) | Comment |
|---|---|---|
| EXTNAME | time-coordinate | |
| BTYPE | time axis | |
| BUNIT | [s] |
Level-2 Description
FIRS Level-2 data files contain results of spectropolarimetric inversions carried out using the Hazel code. There are two different versions of Hazel data file, which can usually be distinguished by their target, file size, and author. The original FIRS Level-2 data products were created by Dr. Shuo Wang for synoptic studies of quiet-sun filaments. These data files contain inversion results for a single chromospheric component, and tend to be windowed to a single filament, which is well-masked. These data are packaged as FITS files with a single extension containing the inversion results as a data cube of the shape (9, nx, ny). The zeroth axis (in Python handling, axis 3 in FITS handling) corresponds to results of:
| Parameter Name | Comment |
|---|---|
| Bx: | In Hazel coordinates, the X-component of the He I magnetic field |
| By: | The y-component of the same |
| Bz: | The z-component of the same |
| a: | The chromospheric damping parameter |
| beta: | The plasma-beta parameter |
| delta v thermal: | The velocity width induced by thermal motions |
| ff: | The chromospheric filling factor |
| tau: | The optical depth in the He I line |
| v macro | The macroturbulent velocity (mostly instrumental profile |
The new FIRS level-2 data products are created by Dr. Sean Sellers, and have been applied to a wider variety of data sets, including active regions and coronal holes. In addition to the He I line results, the new Level-2 files contain results for the Si I line, using the Hazel wrapper for the SIR photospheric code. There are a total of 14 extensions to the new Level-2 product, making the file size significantly larger (approx 1--2 GB/file), and these extensions correspond to:
| Index | Extension Name (EXTNAME) | Extension type | Comments |
|---|---|---|---|
| 0 | N/A | Header | Header containing file description, no data |
| 1 | CHROMOSPHERE | FITS table | Results of chromospheric inversions from He I line. The preparation code contains the capability to write multiple chromospheric extensions if multi-layer inversions are performed, but the default pipeline uses only one chromosphere. |
| 2 | PHOTOSPHERE | FITS table | Results of photospheric SIR inversions from Si I line |
| 3-6 | Stokes-I, Q, U, or V/Ic | FITS image data | Data cube containing the corresponding Stokes-vector. Since the Hazel preparation part of the pipeline carries out normalization to continuum intensity and low-signal masking, these are included for end-users to directly compare resutls |
| 7-10 | SYNTHETICStokes-I/Q/U/V | FITS image data | Data cube containing the best fit Hazel-synthesized Stokes-vector. Used in conjunction with indices 3-6, end users can compare data to fit results |
| 11 | CHISQ | FITS image data | 2D image containing the final chi-square value for every fit pixel |
| 12 | lambda-coordinate | FITS image data | 1D array containing the wavelength array used in fitting. Since data are windowed to the region around the Si I/He I complex, this is not the same as the lambda extension in Level-1.5 files |
| 13 | time-coordinate | FITS image data | May not be present. If Hazel inversions were performed for the full field, this extension is the same as the level-1.5 extension of the same name, seconds since 00:00 on the observing day at the start of each slit position. |
Level-2 Header Information and FITS Table Contents
Base Information Header
| Key | Value (Ex.) | Comments |
|---|---|---|
| DATE | YYYY-MM-DDTHH:MM:SS | File creation date |
| TELESCOP | DST | |
| INSTRUME | FIRS | |
| DATA_LEV | 2 | Date Level |
| DATE_OBS/STARTOBS | YYYY-MM-DDTHH:MM:SS.000 | Start time of observation, both present |
| DATE_END/ENDOBS | YYYY-MM-DDTHH:MM:SS.000 | End time of observation, both present |
| FOVX/Y | 123.45 | May be different than the Leve-1.5 FOV |
| X/YCEN | 123.456 | Solar-X/Y at center of FOV |
| ROT | 0.123 | Rotation angle from solar north |
| PRSTEP1--5 | HAZEL2-INVERSION | List of all reduction steps, ending with Hazel inversion |
Chromospheric/Photospheric Inversion Result Information
Hazel inversion results are stored in FITS table format. FITS tables are defined by header attributes in the TFORM, TUNIT, TDIM keywords, one per table column. While TDIM can indicate that an entry has a 2-dimensional shape, there is a third dimension accessible, given by the NAXIS header keyword. For Python users, this is all baked in to the astropy FITS handling module, and indexing a table column will return the full 3D object. This is important to know because Chromospheric and Photospheric inversion results are both 3D, but not in the same way. The SIR code that form the back end of the Photospheric inversion codes interpolates final parameters between results at user-defined "nodes", which are defined on an optical depth grid as a height stand-in. While the number of nodes may vary, typically, SIR will output 73 points along this axis, for a data cube of the shape (73, NX, NY), as read by the following python snippet:
import astropy.io.fits as fits
f = fits.open("firs_hazel_HeI_SiI_YYYYMMDD_HHMMSS_l2.fits")
temperature = f[2].data['T']
Note that the depth grid is unrelated to the number of nodes. If a parameter is fit with one node, each of the 73 points will contain the same fit value.
Chromospheres, however, are fit by Hazel itself, and are treated as slabs of plasma, with only an integrated profile in height. In order for them to be handled in the same manner as Photospheres for analysis, they are placed into a structure with a shape of (1, NX, NY). Trust me, this is the best way I could think of to do this. The upshot is that you need to index with 0 to get the 2D map.
The following table gives a list of FITS Table Column names, which extension they are found in (Photospheric, Chromospheric, or Both).
| Key | Which | No. Dimensions | Units | Description |
|---|---|---|---|---|
| logTau | P | 1 | log10(tau) | Only 1-D array in extension, the SIR optical depth grid |
| Bx | B | 3 | Gauss | Magnetic field in the Hazel X-direction. Not disambiguated. |
| By | B | 3 | Gauss | Magnetic field in the Hazel Y-direction. Not disambiguated |
| Bz | B | 3 | Gauss | Magnetic field in the Hazel-Z direction. Does not need disambiguation |
| Bx/y/z_err | B | 3 | Gauss | Estimation of 1-sigma errors in Bx/y/z. Each fit parameter has an associated error, given by the _err keyword. For the rest of this description, these are indicated in the same entry as the fit parameter. |
| T, T_err | P | 3 | Kelvin | Temperature in Kelvin |
| v, v_err | B | 3 | km/s | Doppler LOS velocities |
| vmac | P | 3 | km/s | Macroturbulent velocity. No errors in this parameter |
| vmic, vmic_err | P | 3 | km/s | Microturbulent (thermal) velocity |
| deltav, deltav_err | C | 3 | km/s | Thermal velocity width in the chromosphere |
| tau, tau_err | C | 3 | log10(tau) | Integrated optical depth of the He I triplet |
| a, a_err | C | 3 | Unitless | Chromospheric damping parameter |
| beta, beta_err | C | 3 | Unitless, pressure ratio | Plasma-beta parameter in the chromosphere |
| ff, ff_err | B | 3 | Fractional | Plasma filling factor. Typically, this shows very little in the chromosphere if tau and beta are allowed to vary |
Spectral Profiles, Chi-squared Map Information
The Stokes-I, Q, U, V, SYNTHETICStokes-I, Q, U, V, and CHISQ extension headers are all similar, and contain mostly pointing information. Since much of the Photospheric and Chromospheric parameter headers are devoted to defining FITS table columns, we recommend using the headers from one of these extensions for the purposes of, e.g., creating a sunpy map with a given parameter. The CHISQ extension, in particular, is useful for this purpose. All however, contain the CDELT, CTYPE, CUNIT, CRVAL, CRPIX, and CROTAN keywords from the Level-1.5 file headers (see above).
Data Examples
The following set of figures is reproduced from the upcoming SSODA Archive Paper (Sellers et. al., 2024, in prep). Please do not reproduce without permission.
Example of FIRS Level-1.5 Data Product
Example of FIRS Level-2 Data Product
Image automatically produced during construction of Level-2 FITS file, and stored in the same directory. Useful for quicklook evaluation of inversion quality.
Compared Example of Selected Points at Level-1, 1.5, and 2
