Level 3 FITS file - ITA-Solar/solo-spice-ql GitHub Wiki
- Description
- Creating level 3 FITS files
- Reading a level 3 FITS file
- Structure of a level 3 SPICE FITS file
- Structure of a level 2 SPICE FITS file
- Procedure of creating a level 3 file
Table of contents generated with markdown-toc
Level 2 data for SPICE will be fully-calibrated data-sets, with instrumental effects removed. Level 3 data products will be physical quantities derived from integrated emission line intensities. For example, temperature, density and FIP bias maps. The first step in generating such maps will be automatic Gaussian fitting of the observed emission lines. This will be done with the CFIT software in Solarsoft. Level 3 data products will be produced in the standard data pipeline, and the set of products will be determined by the SPICE consortium. It will be possible for users to run the pipeline, starting at level 1, with modified parameters, flatfields, etc. when desired. The output format for Level 3 data will be fits files, with individual data products stored in separate extensions that may be read using standard fits software. Direct products from line fits (intensity/velocity/widths) will be viewable and modifiable using XCFIT. Specialised routines for displaying secondary derived products such as temperature maps, etc., are not planned at this point.
A level 3 SPICE FITS file consists by default of 2 extensions per window, but it may contain up to 6 extensions per window. All data cubes that are required to recreate the analysis structure, which is used as input to XCFIT_BLOCK, will be recreated if necessary. The keyword header of the first extension (Results) of each window contains all the level 3 specific keywords, such as fit components and fit parameters. The keyword header of the second extension (Data) of each window contains the original header of the level 2 file, but it is saved with no data. The data cube will be fetched from the original level 2 file.
Level 3 SPICE FITS files can be generated using a GUI, either through SPICE_XFILES or SPICE_XCONTROL.
In SPICE_XFILES you can click on the button 'Open file in XControl_L23', which will open SPICE_XCONTROL_L23. This GUI lets you create level 3 data for single windows at a time or for several or all windows in a level 2 file.
When opening a level 2 file in any other way from SPICE_XFILES, it will open SPICE_XCONTROL. There, you will find the button 'Create level 3 files', which opens the GUI SPICE_CREATE_L3_WIDGET.
A level 3 SPICE FITS file can be generated automatically using the following SPICE_DATA method:
spice_object = spice_data(spice_file)
spice_object->create_l3_file(window_index)
The procedure opens XCFIT_BLOCK with the result. The FIT components and its parameters can be edited/adjusted by the user in XCFIT_BLOCK. The level 3 file is then saved into the directory $SPICE_DATA/user/level3/.
Multiple level 3 files can be created by using the procedure SPICE_CREATE_L3_DRIVER. This tool allows to select all level 2 files within a certain time window, and create level 3 files for all of them. Additionally, one can also create overview images from the level 3 data.
The level 3 data can be saved as images. These images are created from level 3 FITS files with the tool SPICE_CREATE_L3_IMAGES. These images can also be created with the above-mentioned SPICE_CREATE_L3_DRIVER.
The easiest way to read and view a level 3 SPICE FITS file is by using SPICE_XFILES. You can search for level 3 files and by selecting one, SPICE_XCONTROL_L23 is opened.
Alternatively, you can read a file also with the function FITS2ANA which returns an array of analysis structures, one per window.
The following links describe the different extensions that may be found in a level 3 file.
This extension contains the results of the fit performed by CFIT_BLOCK. The fit components are saved as keywords in the header, and the calculated parameters for each pixel are stored in the data cube.
This extension contains the original header from the level 2 file. But it does not contain the data cube itself, but rather a link to the extension in the level 2 file.
This extension contains a cube with the wavelength of each pixel. This extension IS NOT SAVED, since it can be recalculated by using the WCS parameters from the level 2 file. It may be saved upon request.
This extension contains the weights of each pixel. It is only saved if there are any non-default values in the cube, i.e. if at least one value is different from 1.0.
This extension contains the 'include' flags of each pixel and fit component. This extension is only saved if there are any non-default values in the cube, i.e. if at least one value is different from 1.
This extension contains the 'constant' flags of each pixel and fit parameter. This extension is only saved if there are any non-default values in the cube, i.e. if at least one value is different from 0.
This extension is not saved in the FITS file, since it can be reproduced using the fit parameters and the original data cube from the level 2 file.
The following link contains the main header of a level 2 SPICE FITS file.
This is an overview of the procedure that creates a level 3 file. A more detailed description can be found here.
-
Step 1: Rearrange a level 2 data cube, so that the 'WAVE' dimension is the first dimension. And pack this cube into a ANA (analysis) structure.
-
Step 2: Find spectral lines of interest in the data by either using a predefined list of lines or by searching peaks. Set some initial values for the fit parameters.
-
Step 3: Fit the data to the fit components and thus find fit parameters for each pixel.
-
Step 4: Optionally, let the user check and/or edit the resulting fit components.
-
Step 5: Transform the ANA structure into a FITS file. Several windows can be saved into one FITS file.
-
Step 6: Save FITS file into the $SPICE_DATA/user/level3 folder. Files created by the pipeline will end up in $SPICE_DATA/level3.