eis-pointing 2018.12.4

Tools to correct the pointing of Hinode/EIS

EIS pointing

Tools to correct the pointing of Hinode/EIS. 🛰

Usage

From the command line

This tool can be run from the command line by calling compute_eis_pointing from the command line:

usage: compute_eis_pointing [-h] [-s STEPS_FILE] [--io IO] [-c CORES]
                            [--cache-aia-data]
                            filename [filename ...]

Determine the pointing of Hinode/EIS.

positional arguments:
  filename              The names of the level 0 EIS files, eg.
                        'eis_l0_20100815_192002'.

optional arguments:
  -h, --help            show this help message and exit
  -s STEPS_FILE, --steps-file STEPS_FILE
                        Path to a yaml file containing the registration steps.
  --io IO               Directory where output files are written,
                        default: ./io.
  -c CORES, --cores CORES
                        Maximum number of cores used for parallelisation,
                        default: 4.
  --cache-aia-data      Cache the AIA data to a file. This uses a lot of
                        storage, but speeds things up when the same raster is
                        aligned for the second time.

Examples (command line):

compute_eis_pointing -c16 eis_l0_20140810_042212
compute_eis_pointing --steps-file steps/shift_only.yml eis_l0_20140810_042212

As a Python module

The tool can also be used from within a Python script, using eis_pointing.compute().

compute(*filename, steps_file=None, io='io', cores=4, cache_aia_data=False)
    Perform all computation steps to determine the optimal EIS pointing.

    Parameters
    ==========
    filename : list
        The names of the level 0 EIS files, eg. 'eis_l0_20100815_192002'.
    steps_file : str or None (default: None)
        Path to a yaml file containing the registration steps.
    io : str (default: 'io')
        Directory where output files are written.
    cores : int (default: 4)
        Maximum number of cores used for parallelisation.
    cache_aia_data : bool (default: False)
        Cache the AIA data to a file. This uses a lot of storage, but speeds
        things up when the same raster is aligned for the second time.

Examples (Python):

import eis_pointing
eis_pointing.compute('eis_l0_20140810_042212', cores=16)
eis_pointing.compute('eis_l0_20140810_042212', steps_file='steps/shift_only.yml')

Installation

Prerequisite: Installing SolarSoft

In order to prepare and export EIS data, this tool calls external IDL routines from SolarSoft. For all features to be available, a functioning installation of SolarSoft containing the EIS instrument is therefore required. If it is not installed in /usr/local/ssw, set the environment variable $SSW to the appropriate path.

If SolarSoft is not installed, steps 1 to 3 of the pipeline will have to be performed manually.

Option 1: Installation using pip

Run pip install eis_pointing.

Option 2: Manual installation

1. Clone this repository.
2. Satisfy the dependencies in requirements.txt, eg. by running pip install -r requirements.txt.
3. Place compute_eis_pointing.py in your $PATH, and eis_pointing/ in your $PYTHONPATH.

Customisation

The registration steps used to find the optimal pointing can be customised in a YAML file, and passed to eis_pointing using the “step file” parameter (see examples above). The file should have a top-level key named step, containing a list of registration steps. Each step must specify at least a type, chosen between shift, rotshift, and slitshift.

By default, EIS data are coaligned with synthetic AIA raster. To coalign with a single AIA image, add the top-level key single_aia_frame: True. In this case, the reference AIA image chosen in the middle of the EIS raster.

See files in steps/ for examples.

When no file is specified, the default behaviour is the same as using steps/full_registration.yml.

Code structure

Pipeline

All the steps required to determine the optimal pointing data from EIS level 0 files are defined in driver.py. The appropriate functions are called by the executable compute_eis_pointing when using the tool from the CLI, or by eis_pointing.compute() when using it as a Python module.

1. Download data Download the required EIS level 0 FITS, and place them in the EIS data files and directory structure described in EIS Software Note #18.

2. Prepare data Generate EIS level 1 FITS from level 0. Both files are found in the EIS data files and directory structure. Performed by eis_pointing/prep.pro.

3. Export windata Generate {io}/windata/eis_windata_<date>.sav from EIS level 1 FITS. This file contains a windata structure generated by the SSW function eis_getwindata (see EIS Software Note #21). Performed by eis_pointing_/export_windata.pro.

4. Compute the EIS emission Sum the EIS windata in wavelength to generate an intensity map of line Fe XII 195.119 Å. Data are saved to {io}/eis_aia_emission/eis_aia_emission_<date>.fits. Performed by eis_pointing.eis_aia_emission.compute().

5. Determine the optimal pointing Determine the optimal pointing for EIS using the intensity map generated at the previous step, and AIA 193 data retrieved from Medoc as a reference. Results from the alignment (ie. new EIS coordinates) are saved to io/pointing/eis_pointing_<date>.fits. Diagnostics plots, correlation cubes, as well as a YAML file containing the results from the coregistration are also saved to {io}/pointing_verification/<date>_*. Performed by eis_aia_registration.py.

Coregistration functions: eis_pointing.coregister

• images contains functions to register images in translation, relatively to another image.
• rasters contains functions to register images in translation and rotation, relatively to a synthetic raster.
• slits functions to register slit positions (ie. vertical columns in an image) separately, relatively to a synthetic raster.
• tools functions shared among the previous submodules.

Utility functions shared by different components eis_pointing.utils

• aia_raster: defines AIARasterGenerator that builds synthetic rasters from AIA data. Also contains SimpleCache and FileCache.
• cli: argument parsing and output display.
• eis, aia.py: functions to handle native EIS and AIA data, filenames, and data queries. This does not take care of transformed data such as AIARasterGenerator.
• files: manage local filenames (ie. those in io/); canonical EIS or AIA filenames are handled in eis.py or aia.py.
• idl: run IDL or SSW code from Python, load and format data returned by IDL. Contains IDLFunction, SSWFunction and IDLStructure.
• num: tools that extend numpy or scipy.
• plots: help generate plots at step 4.
• sun: generic solar computations.

License

This package is released under a MIT open source licence. See LICENSE.txt.