SPICE IDL Quicklook and Data Analysis Software

See Data analysis user's manual for a general description of the SPICE data and its use. You'll also find a link to the Data Products Description Document (DPDD).

If you find any bugs in the quicklook software, please report the issue or send an e-mail to [email protected]

Table of Content

• Setup
• Downloading SPICE FITS files
• Quicklook Software
• Data Analysis Software
• SPICE Data Object
• Level 3 Data Products
• General Utilities
• File Management Utilities
• SPICE-unspecific tools
• Currently Planned Software
• For Developers

Setup

In your shell startup configuration file or in IDL_STARTUP, include SPICE in the SSW_INSTR environment variable and define the SPICE_DATA environment variable:

setenv SSW_INSTR "gen so spice"
setenv SPICE_DATA "~/spice_data"

Update SolarSoft to include the SPICE tools:

ssw_upgrade, /so, /spice, /iris, /spawn

Some of the software from the IRIS branch is used in the SPICE software and is therefore required. It is not necessary to set it as an instrument, since it will be included implicitly when SPICE is included in SSW_INSTR.

Downloading SPICE FITS files

SPICE FITS files can be downloaded with the tool SPICE_WGET_FILES.

Alternatively, files can be downloaded manually from this website or by using the Solar Orbiter Archive.

Quicklook Software

All quicklook software can be accessed through the GUI SPICE_XFILES. You can call it using this command:

IDL> spice_xfiles

This will open a window, which lets you search your local hard disk for SPICE files. Selecting a level 2 file will call SPICE_XCONTROL, which in turn opens a new window. In this window you'll get an overview of the content of the selected FITS file, and you can access the different quicklook software, which are:

• SPICE_XDETECTOR: This tool displays the windows superimposed on the whole SPICE detector.
• SPICE_RASTER_BROWSER: This routine is used to browse 3D SPICE data-cubes.
• SPICE_XRASTER: This tool displays all exposures of the selected windows in a row.
• SPICE_XWHISKER: This tool is used to display 2-D spectroscopic data as whisker plots (images), i.e. Intensity[wavelength, y]. FITS file must contain more than one exposure.
• SPICE_XMAP: This tool is used to display 2-D (or higher) data. FITS file must contain more than one exposure.

Selecting a level 3 file will call SPICE_XCONTROL_L23, which in turn opens a new window. This gives you an overview of existing level 2 and level 3 data of the selected file.

Data Analysis Software

• SPICE wrapper for xcfit (Interactive line fitting)
  • SPICE_DATA::xcfit_block

  ana = spice_data->xcfit_block(window_index)
  

Coming soon:

• “Masking” - averaging spectra over spatial regions (à la eis_mask_spectrum/pixel_mask_gui)

SPICE Data Object

We defined a SPICE data object, called SPICE_DATA, which can be initiated with a SPICE FITS file. This object contains many methods to handle the data and the header contained in the given FITS file. It can be created using this command:

IDL> obj = spice_data(spice_file)
IDL> obj->help

NOTE: It is a little-known but very handy feature of IDL objects that you can simply write class_name(<constructor params>) instead of obj_new('class_name',<constructor params>).

The second line will print out all available methods of the object.

Level 3 Data Products

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.

• See here ( Level 3 FITS file ) for more details on how to create, edit and view level 3 files.

General Utilities

• SPICE_GETWINDATA: This routine returns the SPICE data structure for one spectral window. The format is chosen to copy the Hinode/EIS routine EIS_GETWINDATA.

File Management Utilities

There are several useful tools to manage SPICE files:

• SPICE_WGET_FILES: This tool mirrors SPICE FITS files from Oslo or Paris and cleans up any old files no longer on the server.
• SPICE_INGEST: This tool will move your downloaded SPICE FITS files to the appropriate location in your $SPICE_DATA path.
• SPICE_INGEST_REORDER: This routine can be used to reorder your SPICE files.
• SPICE_FIND_FILE: This program is also used by SPICE_XFILES. It is a very flexible tool to search for files on your local hard drive.
• SPICE_FIND_OBSERVATIONS: This routine searches the SPICE catalog to find observations where the specified pointing falls within the SPICE field-of-view at the specified date/time or range.
• SPICE_CAT: This program allows filtering/sorting/selection of the contents in spice_catalog.txt which contains information about all available (not necessarily locally) SPICE FITS files. This tool can also be called from within SPICE_XFILES.
• SPICE_GEN_CAT: This program creates a file called spice_catalog.txt in the $SPICE_DATA/ directory (but other paths can be specified), with various information on the content of the files found in the directory hierarchy below that path.
• SPICE_FILE2INFO: This routine takes as input a SPICE filename (or list of files) and extracts information from the filename.
• SPICE_REMOVE_OLD_FILES: Remove earlier versions of SPICE fits files.

SPICE-unspecific tools

• ANA2FITS
  • This procedures saves all information of one or more ANA structures into a FITS file. ANA structures are used in CFIT, CFIT_BLOCK, XCFIT, XCFIT_BLOCK.
• FITS2ANA
  • This function reads a FITS file that was written by ANA2FITS and returns one or more ANA structures.
• PRITS_TOOLS
  • This is a collection of various, useful tools.

Currently Planned Software

The plan is to provide approximately the same functionality for SPICE data as what is already available for IRIS/EIS data. Much of this is achieved by ensuring that SPICE data are stored and handled in IDL in a similar way to data from IRIS/EIS. Nevertheless, significant changes to the existing software may be necessary to account for differences in instrument data.
Below is a top-level listing of functionalities, in a rough and preliminary prioritised order, with reference to corresponding heritage routines in parentheses (where appropriate). Note that not all software will necessarily be available for the first remote sensing window, hence prioritization is important.
In general, all functionalities in the heritage routines will be preserved as far as technically possible.

• SPICE object (iris_data)
  • SPICE_DATA
  • Implemented, continuous improvement

  obj = spice_data(spice_file)
  obj->help
  

• DEPRECATED: Routine to read SPICE FITS file into an object (iris_obj)
  • SPICE_OBJECT
  • Done (but now deprecated, use simply ``spice_data(spice_file)```)

  obj = spice_object(spice_file)
  obj->help
  

• A 3D data-cube viewer (iris_raster_browser)
  • SPICE_RASTER_BROWSER
  • Initial working version
  • Dumbbells are shown

  spice_raster_browser, spice_file/spice_object [, quiet=quiet, yoffsets=yoffsets, $
      chunk_size=chunk_size, retina=retina, no_goes=no_goes]
  

• Whisker plot viewer (iris_xwhisker)
  • SPICE_XWHISKER
  • Initial working version
  • Animation with ximovie doesn’t work yet, might be a bigger change

  spice_xwhisker, spice_file/spice_object, line [, group_leader=group_leader, ncolors = ncolors]
  

• Detector data extraction (iris_getwindata)
  • SPICE_GETWINDATA
  • Initial working version
  • Keywords keep_sat, calib and perang are ignored for now

  data = spice_getwindata, spice_file/spice_object, window_index [, keep_sat=keep_sat, $
      clean=clean, wrange=wrange, ixrange=ixrange, normalize=normalize, $
      calib=calib, perang=perang, verbose=verbose, quiet=quiet]
  

• Detector viewer (iris_xdetector)
  • SPICE_XDETECTOR
  • Initial working version
  • binned images including intensity (1D) images expanded correctly
  • Dumbbells shown correctly
  • Animation with ximovie doesn’t work yet, might be a bigger change

  spice_xdetector, spice_file/spice_object, window_indices [, group_leader=group_leader, $
      ncolors = ncolors]
  

• Spectroheliogram viewer (iris_xraster)
  • SPICE_XRASTER
  • Initial working version
  • Animation with ximovie doesn’t work yet, might be a bigger change

  spice_xraster, spice_file/spice_object, window_indices [, group_leader=group_leader, $
      ncolors = ncolors]
  

• Intensity map viewer (iris_xmap)
  • SPICE_XMAP
  • Initial working version

  spice_xmap, spice_file/spice_object [, linelist = window_index, group_leader=group_leader, $
      ncolors = ncolors]
  

• Interactive line fitting (xcfit)
  • SPICE_DATA::xcfit_block
  • Initial working version

  ana = spice_object->xcfit_block(window_index)
  

• “Masking” - averaging spectra over spatial regions (eis_mask_spectrum/pixel_mask_gui)
• S/W assisting in organization of SPICE files on user’s computer (iris_ingest, iris_find_file)
  • Implemented
  • SPICE_INGEST
  • SPICE_FIND_FILE

  spice_ingest, Filename [, force=force, index=index, help=help]
  Result = spice_find_file(Time [, LEVEL=LEVEL, TOP_DIR=TOP_DIR, COUNT=COUNT, /SEQUENCE, /ALL, /QUIET ] )
  

• GUI for selection of files and quicklook tools (iris_xfiles, iris_xcontrol)
  • SPICE_XFILES
  • SPICE_XCONTROL
  • Implemented
  • spice_xcontrol will be called by spice_xfiles when user selects a file

  spice_xfiles
  

• Display EUI/PHI images similar to IRIS SJI images (iris_raster_browser)
• Display STIX data similar to GOES data (iris_raster_browser)

For Developers

This repository includes a pre-commit git hook, that updates a specific line of each modified file with the current date and time. The line with this format will be edited:

; $Id: 2020-11-02 13:07 CET $

If the file you modified, does not contain this line yet, please add it, preferably append it to the procedure description at the beginning of the file.

To make git aware of this hook, run this command after cloning the repository:

cd path_of_repository
git config --local core.hooksPath .githooks/
chmod +x .githooks/*

Git will then run the script ./githooks/pre-commit every time you commit something. This script will check each modified and staged file whether there is a line with the above format, and if yes, updates date and time and adds these changes to the commit.