[{ALLOW edit EISMainUsers}]
[{ALLOW view Anonymous}]



!!!EIS data analysis guide

This guide describes how to access, calibrate and derive scientific results from the EIS instrument on Hinode. For a description of EIS and its observing modes please consult the instrument paper, [Culhane et al. (2007)|http://adsabs.harvard.edu/abs/2007SoPh..243...19C], and the [MSSL Science Centre webpage|http://solarb.mssl.ucl.ac.uk:8080/SolarB/].

All software described here is written in IDL and distributed through the [Solarsoft distribution|https://www.lmsal.com/solarsoft/]. %%(color:red;)__NEW!__%% NRL have developed an EIS analysis package written in Python called [EISPAC|EISPAC].

If you are new to Hinode and EIS, please check our [guide to Hinode and EIS terminology|EISTerminology].

[A list of all EIS publications|https://pyoung.org/hinode/publications/eis_publications_summary.html].

!!Tutorials

The following sections describe individual steps in going from finding data to deriving scientific results. Below we provide tutorials that take users through these steps for example data-sets. 

[Tutorial for narrow slit data|TutorialSlit] (1", 2" slits)

[Tutorial for slot data|TutorialSlot] (40", 266" slits)

!!Searching and downloading EIS data

Each country contributing to the Hinode mission provides access to the data through web portals. Each one offers different capabilities and so it is recommended that you try each to familiarize yourself with the methods for searching for data. Web links to the four sites are given below.

[Hinode Science Data Centre (Europe)|http://elnath.uio.no/search/API] \\

[MSSL Science Centre (UK)|http://solarb.mssl.ucl.ac.uk:8080/SolarB/]\\

[Hinode Data Centre, DARTS (Japan)|http://darts.isas.jaxa.jp/hinode]\\

[Virtual Solar Observatory (US)|http://virtualsolar.org]

In addition, it is possible to download EIS data directly from IDL:

[IDL command line options for downloading data|CommandLineDownload]

%%(color:red;)__NEW!__%% The [EIS Mapper|https://eismapper.pyoung.org] site allows you to quickly see where EIS was pointed on a given day, by overplotting on a full disk EUV image.

The large quantity of EIS data coupled with the large number of free parameters (raster size, wavelength windows, slit choice) means that it can be quite difficult to find the perfect data-set if you don't already know which study you want. Check out [Tips for finding the perfect data-set|TipsPerfect] to get some hints on searching for data. Also take a look at %%(color:red;)__NEW!__%%[the list of most commonly-used EIS studies|MostCommon].

[How to find data from the EIS response studies|TriggerStudies] (e.g., flare triggers).

For information about where to store EIS data files on your computer after you've downloaded them, please check [EIS Software Note No. 18|ftp://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/18_FILES/eis_swnote_18.pdf].

[What was EIS doing yesterday?|EISDoing] How to find out what EIS observations were being performed yesterday, last week or anytime.


[Important dates during the EIS mission|EISHistory]. This gives a timeline of significant events during the EIS mission that may affect your data analysis.


[Reference data-sets|EISRef].

!!Calibrating EIS data

Calibration of EIS data is performed with a single IDL routine, EIS_PREP, which converts a level-0 FITS file (raw data) to a level-1 FITS file (calibrated data). Note that the data archives listed above do not distribute level-1 files, so the user needs to perform the calibration. It is highly recommended that the user perform calibration before browsing the data as detector artifacts called warm pixels make browsing the raw data difficult.

The standard call for eis_prep is:

{{{
IDL> eis_prep, filename, /quiet, /retain, /default, /save
}}}

%%(color:red;)__IMPORTANT NOTE__%%: the /correct_sensitivity keyword is no longer recommended as of 8 October 2013. The recommendation for all EIS files is to use the call above, and then apply a calibration correction factor as a post-processing step. Please check the [calibration discussion page|EISCalibration]  for more details.


%%(color:red;)__NOTE FOR SLOT DATA__%%: please check [calibrating slot data|SlotCalib].

An explanation of the eis_prep keywords and a description of the calibration steps performed by eis_prep are available in [EIS Software Note No. 1|ftp://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/01_EIS_PREP/eis_swnote_01.pdf].

eis_prep can take a long time to process a data-set, but it can be speeded up by using a dynamically-loadable module (DLM). Please check out [setting up a DLM for eis_prep|DLMeisprep] for more details.

%%(color:red;)__UPDATE, 12-Dec-2019__%%: A significant change to EIS_PREP has been made, relating to the removal of residual warm pixels and cosmic rays. Please check out [EIS Software Note No. 24|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/24_COSMIC_RAYS/eis_swnote_24.pdf] for more details.

!!Taking a quick-look at your data

For browsing a data-set there are several 'quicklook' tools available that can be accessed by first calling a single IDL widget called XFILES:

{{{
IDL> xfiles
}}}

The widget allows you to choose an EIS file by manually typing in the path to the EIS file. Make sure to change 'eis_l0_*' to 'eis_l1_*' in the 'Set search filter' box to look for level-1 files rather than level-0 files. After confirming your selection a new widget called XCONTROL pops up which allows the user to access the five quicklook tools:

[Control|QuicklookControl] - find basic info on your data, run eis_prep, access QL tools.

[Detector|QuicklookDetector] - displays detector images.

[Browser|QuicklookBrowser] - allows user to browse the 3D data cubes (wavelength-X-Y) obtained from narrow slit observations.

[Spectroheliogram|QuicklookSpectroHeliogram] - for a specified line shows a solar-Y vs. wavelength plot for each exposure.

[Whisker|QuicklookWhisker] - for a specified line shows a solar-X vs. wavelength plot for each exposure.

[Intensity map|QuicklookIntensity] - for a specified line shows an intensity image.

!!EIS objects and structures

A complete data-set is read into IDL as an object as follows:

{{{
IDL> data=obj_new('eis_data',filename)
}}}

where 'filename' is the name of the level-1 file (a level-0 file can be read in the same way). The contents of the object can be read and manipulated through a large number of methods and an overview of some of the most useful methods is given below.

[EIS object methods|EISmethods]

The routine [EIS_GETWINDATA|EISGetWindata] is also available if you want to extract a single EIS data window into an IDL structure. Some routines (e.g., EIS_AUTO_FIT) require as input the structures produced by EIS_GETWINDATA.


!!Narrow slit data (1", 2" slits)

The 1" and 2" slits return emission line spectra and a basic task for such data-sets is to fit Gaussians to the emission lines to return intensity, centroid and width information. Gaussian fitting routines available to EIS users are described below. The routines correct for most instrumental effects, but users should familiarize themselves with some of these effects through the software notes listed below:

* Warm and hot pixels (Software Notes 6 and 13)
* Orbital drift of line centroids (Software Note 5)
* EIS slit tilts (Software Note 4)
* EIS spectrum tilt (Software Note 3)

There is one important instrumental effect that potentially can affect Doppler shift studies, but for which there is not a software fix at present:

* [Spatial offset between velocity and intensity features|Spatial offset of intensity and velocity features]

!Gaussian fitting routines

Fitting a Gaussian function to an emission line yields measures of the line intensity, centroid (velocity) and width. Single Gaussian fits to individual lines are possible using [EIS object methods|EISmethods], while more sophisticated fitting options are available through the EIS_AUTO_FIT and SPEC_GAUSS_EIS routines available in Solarsoft. Documents describing these routines and giving examples are listed below.

[EIS_AUTO_FIT and SPEC_GAUSS_EIS: Gaussian fitting for the Hinode/EIS mission (EIS Software Note 16)|ftp://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/16_AUTO_FIT/eis_swnote_16.pdf]\\
[Gaussian fitting examples using EIS_AUTO_FIT (EIS Software Note 17)|ftp://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/17_AUTO_FIT_EXAMPLES/eis_swnote_17.pdf]


Users should be aware that EIS line profiles can often take on non-Gaussian shapes which may contain valuable scientific information (e.g., [Chifor et al. 2008|http://adsabs.harvard.edu/abs/2008A%26A...481L..57C,], [De Pontieu et al. 2009|http://adsabs.harvard.edu/abs/2009ApJ...701L...1D,]).

!Line ratio maps and density diagnostics

Some emission line ratios are sensitive to the electron density, and software is available to take the line fit structures output by EIS_AUTO_FIT and convert them to electron density maps. The density then allows the emitting column depth of the plasma to be determined which in turn allows the filling factor of the plasma to be estimated. The document below describes how this done, making use of atomic data from the [CHIANTI database|http://www.chiantidatabase.org].

EIS Software Note #15 - [Deriving densities from Hinode/EIS data|ftp://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/15_DENSITY/eis_swnote_15.pdf]

!Emission measure

When line intensities are available from several different ions, then an emission measure (EM) or differential emission measure (DEM) distribution can be constructed. No specific EIS software is available for doing this and so users are referred to software in the CHIANTI database, in particular:

integral_calc.pro:  computes an EM value from a single line intensity\\
chianti_dem.pro:  computes a DEM distribution from multiple line intensities

Another popular DEM code is available within the [PINTofALE|http://hea-www.harvard.edu/PINTofALE/] software package.



!!Slot data (40", 266" slits)

The EIS slots produce images rather than spectra, and the most common application will be to produce movies from the slot rasters in a range of emission lines. 

The data should be calibrated with eis_prep in the same way as narrow slit data. If you're working with slot rasters, then you can assemble the data into a single 2D image within a 'windata' structure with

{{{
IDL> eis_readslot,file,wd,win=195.12,/estimate
}}}

(see also the [slot tutorial|TutorialSlot]).

To create an IDL map from slot rasters, do:

{{{
IDL> map=eis_slot_map(file)
}}}

where you'll be asked to choose a wavelength window.



!!Pointing and co-alignment

Most EIS users will be analyzing data-sets from multiple instruments and so it is necessary to determine where an EIS raster is positioned relative to the other instruments. Usually the pointing information within an EIS file will not be good enough to accurately co-align data-sets and so cross-correlation will be necessary.

* [Obtaining SDO cutout images for EIS rasters|AIAEIS]
* [Obtaining pointing information from EIS data|EISPointing]
* [Creating an IDL map from EIS data|EISMaps]
* [Co-aligning EIS and SOT images|EISSOTcoalign]
* [The EIS plate scale|EISPlateScale]

!!Coordination with other observatories

[Parker Solar Probe|EISPSP]

!!EIS Software Notes

A series of Software Notes have been written that give details about various technical aspects related to the EIS mission. Some of these documents are published are Zenodo and so have a citable DOI. Please use this if you reference the documents in a paper.

[Software Note No. 1|https://doi.org/10.5281/zenodo.6339609] - Calibrating EIS data: the EIS_PREP routine (Peter Young) %%(color:blue;)[[Zenodo]%%\\
[Software Note No. 2|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/02_RADIOMETRIC_CALIBRATION/eis_swnote_02.pdf] - Radiometric calibration (John Mariska)\\
[Software Note No. 3|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/03_GRATING_DETECTOR_TILT/eis_swnote_03.pdf] - Spatial Y-offsets between different wavelengths (spectrum
  tilt and CCD offset) (Peter Young)\\
[Software Note No. 4|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/04_SLIT_TILT/eis_swnote_04.pdf] - Slit tilts (Peter Young)\\
[Software Note No. 5|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/05_WAVELENGTH_CORRECTION/eis_swnote_05.pdf] - Orbital variation of EIS wavelength scale (Sugura Kamio, Terje Fredvik, Peter Young)\\
[Software Note No. 6|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/06_HOT_WARM_PIXELS/eis_swnote_06.pdf] - Hot and Warm pixels (Louisa Kennedy, Peter Young)\\
[Software Note No. 7|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/07_LINE_WIDTH/eis_swnote_07.pdf] - Instrumental line widths for the narrow slits of EIS (Peter Young)\\
[Software Note No. 8|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/08_COMA/eis_swnote_08.pdf] - EIS Point Spread function (Ignacio Ugarte-Urra)\\
[Software Note No. 9|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/09_POINTING/eis_swnote_09.pdf] - EIS Pointing (John Mariska)\\
[Software Note No. 10|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/10_DARK_CURRENT/eis_swnote_10.pdf] - Dark Current (Paul Bryans)\\
[Software Note No. 11|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/11_JPEG_COMPRESSION/eis_swnote_11.pdf] - JPEG Compression (Harry Warren) \\
[Software Note No. 12|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/12_STRAY_LIGHT/eis_swnote_12.pdf] - Stray Light (Ignacio Ugarte)\\
[Software Note No. 13|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/13_INTERPOLATION/eis_swnote_13.pdf] - Interpolation of missing EIS data (Peter Young)\\
[Software Note No. 14|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/14_BP_TRIGGER/eis_swnote_14.pdf] - The EIS Bright Point Trigger (Peter Young, Khalid Al-Janabi)\\
[Software Note No. 15|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/15_DENSITY/eis_swnote_15.pdf] - Deriving densities, column depths and filling factors from Hinode/EIS data (Peter Young)\\
[Software Note No. 16|https://doi.org/10.5281/zenodo.6339584] - EIS_AUTO_FIT and SPEC_GAUSS_EIS: Gaussian fitting routines for the Hinode/EIS mission (Peter Young) %%(color:blue;)[[Zenodo]%%\\
[Software Note No. 17|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/17_AUTO_FIT_EXAMPLES/eis_swnote_17.pdf] - Gaussian fitting examples using the EIS_AUTO_FIT routine (Peter Young)\\
[Software Note No. 18|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/18_FILES/eis_swnote_18.pdf] - EIS data files and directory structure (Peter Young)\\
[Software Note No. 19|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/19_DATABASE/eis_swnote_19.pdf] - How to access and use the EIS databases (Peter Young)\\
[Software Note No. 20|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/20_EIS_AIA_COALIGN/eis_swnote_20.pdf] - EIS/AIA coalignment (John Mariska)\\
[Software Note No. 21|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/21_WINDATA/eis_swnote_21.pdf] - The WINDATA routines for EIS data analysis  (Peter Young)\\
[Software Note No. 22|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/22_QUICKLOOK_AND_TIMELINE_DB/eis_swnote_22.pdf] - EIS Quicklook Data Processing and Timeline Database Retrieval  (John Mariska)\\
Software Note No. 23 - In preparation\\
[Software Note No. 24|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/24_COSMIC_RAYS/eis_swnote_24.pdf] - EIS_PREP: removing residual warm pixels and cosmic rays  (Peter Young)\\
[Software Note No. 25|https://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/25_IDL_SEARCH/eis_swnote_25.pdf] - How to search for and download EIS files from IDL  (Peter Young)\\


These documents are also available in the EIS Solarsoft distribution, in $SSW/hinode/eis/doc/eis_notes.