Package: eis-pointing
EIS pointingTools to correct the pointing of Hinode/EIS.This Python package implements the method described in the paperPelouze et al. 2019, Sol Phys 294:59.UsageFrom the command lineThis tool can be run from the command line by callingcompute_eis_pointing: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-c16eis_l0_20140810_042212
compute_eis_pointing--steps-filesteps/shift_only.ymleis_l0_20140810_042212As a Python moduleThe tool can also be used from within a Python script, usingeis_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):importeis_pointingeis_pointing.compute('eis_l0_20140810_042212',cores=16)eis_pointing.compute('eis_l0_20140810_042212',steps_file='steps/shift_only.yml')InstallationInstall the latest release by running:pip install eis_pointing.Alternatively, the latest version can be installed from GitHub by cloning this
repository withgit clone https://github.com/gpelouze/eis_pointing, then
runningcd eis_pointing, andpip install ..Optional: install SolarSoftBefore computing the optimal pointing, this tool can download, prepare, and
export the EIS data by calling external IDL routines fromSolarSoft. For
these features to be available, a functioning installation of SolarSoft
containing the EIS instrument is required.Install SolarSoft,
and set the environment variable$SSWto your installation path (by default,
SolarSoft is assumed to be installed installed into/usr/local/ssw).It is perfectly fine not to install or configure SolarSoft to run with this
tool. In this case, you will need to manually download the EIS level0 FITS,
prepare them into level1 FITS, and save a windata structure containing the
Fe XII 195.119 Å line to a.savfile placed in<io directory>/windata/eis_windata_<date>.sav.
Seepipelinefor details on how to do this.CustomisationThe registration steps used to find the optimal pointing can be customised in a
YAML file, and passed toeis_pointingusing the--steps-fileparameter (see
examples above). The file should have a top-level key namedstepsthat
contains a list of registration steps. Each step must specify at least atype, chosen betweenshift,rotshift, andslitshift.By default, EIS data are coaligned with synthetic AIA raster. To coalign with a
single AIA image, add the top-level keysingle_aia_frame: True. In this case,
the reference AIA image chosen at the middle of the EIS raster.See files insteps/for examples.When no file is specified, the default behaviour is the same as usingsteps/full_registration.yml.Code structurePipelineAll the steps required to determine the optimal pointing data from EIS level 0
files are defined indriver.py. The appropriate functions are called by the
executablecompute_eis_pointingwhen using the tool from the CLI, or byeis_pointing.compute()when using it as a Python module.Download dataDownload the required EIS level 0 FITS,
and place them in the EIS data files and directory structure
described inEIS Software Note #18(eg.$HINODE_DATA/eis/level0/2014/08/10/eis_l0_20140810_042212.fits).Prepare dataGenerate EIS level 1 FITS from level 0, and save it to the
EIS data files and directory structure
(eg.$HINODE_DATA/eis/level1/2014/08/10/eis_l1_20140810_042212.fits).
Performed byeis_pointing/prep.pro, which calls the SolarSoft routineeis_prep.pro.Export windataSave awindatastructure containing the
Fe XII 195.119 Å line, obtained using the SolarSoft functioneis_getwindata(seeEIS Software Note #21).
The structure is saved to<io>/windata/eis_windata_<date>.sav(eg../io/windata/windata_20140810_042212.sav).
Performed byeis_pointing/export_windata.pro.Alternative to steps 1-3 without SolarSoftIf SolarSoft is not installed or
configured, you will need to separately generate a windata structure containing
the Fe XII 195.119 Å line, and save it to<io>/windata/eis_windata_<date>.sav.Example (SSW):wd=eis_getwindata('eis_l1_20140810_042212.fits',195.119,/refill)save,wd,filename='./io/windata/windata_20140810_042212.sav'Once this is done, run the tool normally, either from thecommand
line, or as aPython module. It
will detect the existing.savfile, and skip steps 1-3.Compute the EIS emissionGenerate an intensity map of the Fe XII 195.119 Å line by summing
the spectra between 194.969 and 195.269 Å. Data are saved to<io>/eis_aia_emission/eis_aia_emission_<date>.fits(eg../io/eis_aia_emission/eis_aia_emission_20140810_042212.fits).
Performed byeis_pointing.eis_aia_emission.compute().Determine the optimal pointingDetermine the optimal pointing for EIS
using the intensity map generated at the previous step, and AIA 193 data
retrieved fromMedocas a reference.  (The AIA FITS are
downloaded to./sdo/aia, or to$SDO_DATA/aia/if the environment
variable$SDO_DATAis set set.)
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 byeis_pointing.eis_aia_registration.optimal_pointing().Coregistration functions:eis_pointing.coregisterimagescontains functions to register images in translation, relatively to
another image.rasterscontains functions to register images in translation and rotation,
relatively to a synthetic raster.slitsfunctions to register slit positions (ie. vertical columns in an
image) separately, relatively to a synthetic raster.toolsfunctions shared among the previous submodules.Functions shared by different componentseis_pointing.utilsaia_raster: definesAIARasterGeneratorthat builds synthetic rasters
from AIA data. Also containsSimpleCacheandFileCache.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 asAIARasterGenerator.files: manage local filenames (ie. those inio/); canonical EIS or AIA
filenames are handled ineis.pyoraia.py.idl: run IDL or SSW code from Python, load and format data returned by
IDL. ContainsIDLFunction,SSWFunctionandIDLStructure.num: tools that extend numpy or scipy.plots: help generate plots at step 4.sun: generic solar computations.Reference / LicenseIf you use this package for a publication, please acknowledge the following
paper:Pelouze et al. 2019, Sol Phys 294:59.This package is released under a MIT open source licence. SeeLICENSE.txt.