
\documentclass[11pt]{article}

\usepackage[dvips]{graphicx}      %% FOR INCLUDING GRAPHICS
\usepackage{natbib}
\usepackage{epsf}

%% ----------------------------------------------------------------------
%% Add specials here
%% ----------------------------------------------------------------------

\def\ion#1#2{#1\,{\sc #2}\relax}  %% 

%% ----------------------------------------------------------------------
%% Modify: 
%%   Note number, version number and date
%%   Title
%%   Author and affiliation 
%% ----------------------------------------------------------------------

\setlength{\oddsidemargin}{0in}         %  1 inch (0 + 1) from left.
\setlength{\topmargin}{-0.5in}          %  1 inch (1.5 - 0.5) from top.
\setlength{\textwidth}{6.5in}           %  1 inch (8.5 - 1 - 6.5) from right.
\setlength{\textheight}{9in}            %  1 inch (11 - 1 - 9) from bottom.

\addtolength{\parskip}{0.5\baselineskip}

%  The environment centerpage centers text vertically on the page.  This is
%  useful within a titlepage environment.

\newenvironment{centerpage}{\mbox{} \protect\vspace*{\fill}}{
        \protect\vspace*{\fill} \mbox{} \protect\\ \mbox{}}

\newcommand{\lam}{$\lambda$}
\newcommand{\arcsec}{$^{\prime\prime}$}
\newcommand{\kms}{km~s$^{-1}$}

\begin{document}                
%\bibliographystyle{plain}               % Define bibliography style.

\begin{titlepage}
\hrule
\noindent\textbf{EUV IMAGING SPECTROMETER}\\
\vspace{-0.7\baselineskip}\\
{\noindent\Huge\bf Hinode}
\vspace{2mm}
\hrule
\vspace{3mm}
\centerline{\bf EIS SOFTWARE NOTE No. 5}
\vspace{3mm}
\hrule
\noindent Version 1.2 \hfill 18 August 2021
\vspace{2mm}
\hrule

\begin{centerpage}

\begin{center}
{\Large\bf Orbital drift of the EIS wavelength scale}\\
\mbox{}\\
\mbox{}\\
Suguru Kamio\\
Max-Planck-Institut f\"ur Sonnensystemforschung\\
Max-Planck-Str. 2\\
37191 Katlenburg-Lindau\\
Germany\\
\mbox{}\\
\mbox{}\\
Terje Fredvik\\
Institute of Theoretical Astrophysics\\
University of Oslo\\
P.O. Box 1029 Blindern\\
N-0315 Oslo\\
Norway\\
\mbox{}\\
terje.fredvik@astro.uio.no\\
\mbox{}\\
\mbox{}\\
\mbox{}\\
Peter Young\\
NASA Goddard Space Flight Center\\
U.S.A.\\
\mbox{}\\
\end{center}

\end{centerpage}

\end{titlepage}

%% ----------------------------------------------------------------------
%% The document!
%% ----------------------------------------------------------------------


\textbf{UPDATE (18-Aug-2021)}: The method described by  \citet{kamio10} no longer
works correctly and should not be used for data obtained from 2018
onwards. Generally you can recognise that the method is not working if
you see vertical bands in the Doppler maps with amplitudes of around
10~km~s$^{-1}$. The best solution is to fit the emission line of
interest and then  identify a band of quiet Sun. By averaging the line
centroid over this band you will see the orbital variation, which can
then be subtracted . The
text below is retained from the previous version of the document (1.1).


\section{Overview}


If a Gaussian is  fit to an emission line profile over an entire
raster, then plotting the resulting image of the centroid variation
shows a strong oscillation in the X-direction. An example is shown in
Fig.~\ref{fig.orbital}, where the alternating bands of red and blue
correspond to red and blue shifts of the emission line. The period of
the oscillation is 98~mins and corresponds to the orbital period of
the spacecraft, thus the oscillation is clearly due to thermal effects
related to the satellite's orbit around the Earth. In this document we
refer to this effect as ``spectrum drift'' and we 
describe methods of correcting it.


\begin{figure}[h]
\centerline{\epsfxsize=12cm\epsfbox{orbital.eps}}
\caption{A velocity map derived from an EIS raster. EIS rasters from
  right-to-left, and the vertical bands of blue and red correspond to
  the spectrum drift during the raster.}
\label{fig.orbital}
\end{figure}


\section{What causes the oscillation?}

The Hinode spacecraft is oriented such that it always points at the
Sun, and it does not rotate relative to the Sun. This means that 
each side of
the spacecraft  receives a variable illumination
from the Earth as the spacecraft orbits the Earth. For EIS this means
that in some parts of the orbit the 
instrument is directly illuminated by the Earth, and in other parts it
is shadow behind SOT.

The movement of the emission lines on the CCD is thus understood as
being due to an oscillation in the angle of the reflecting surface
of the EIS grating. The changing temperature of the instrument in the
vicinity of the grating leads to a small rotation of the grating
position. The effect corresponds to a $\pm$1.5 pixel amplitude
oscillation in the positions of the lines on the detector. The
EIS pixels have a size of 13.5~$\mu$m and the grating--detector
separation is 1.44~m thus the tilt in the grating position is only
0.0008$^\circ$. However, Fig.~\ref{fig.orbital} shows that this tiny
movement dominates the Doppler shifts due to real motions on the Sun. 

\section{Properties of the spectrum drift}

The paper of \citet{kamio10} gives a thorough discussion of the
spectrum drift. Some key points are given below.

\begin{itemize}
\item The amplitude of the oscillation is about 1.5 pixels and is the
  same for all wavelengths. This means, however, that in velocity
  space the amplitude varies with wavelength, being around 50~\kms\
  for \ion{Fe}{xii} \lam195.12 and 35~\kms\
  for \ion{Fe}{xv} \lam284.16.
\item During the eclipse season (April--August) the oscillation
  significantly deviates from a sinusoidal pattern.
\item Over a day the line centroids oscillate about a center which
  itself drifts with time. This drift is seasonal in nature and due to
  the varying separation of the Sun and the Earth.
\end{itemize}

\section{Correcting for the spectrum drift}

Initial efforts at correcting the spectrum drift involved using the
science data themselves. Typically the strongest line in the spectrum,
\ion{Fe}{xii} \lam195.12, was fit at each pixel in a raster, and the
centroid averaged in the Y-direction. This average centroid yielded
the spectrum drift during the course of the raster which could then be
used to correct other lines. The method assumes there are no large
scale flows within the raster that would distort the spectrum drift. A
common variation for active region data is to identify a quiet part of
the raster and then only average over this region so that any flows
within the active region do not affect the determination of the
spectrum drift.

Since the EIS instrument contains 31 temperature sensors that yield
values with a 10~s cadence, then an alternative method of determining
the spectrum drift is to correlate the temperature sensor readings
with the spectrum line positions through a model. This work was
performed by \citet{kamio10} and, since around 2010 September, this
new method is now the default way of correcting for the spectrum
drift. Since the temperature sensor data form part of the EIS
housekeeping data stream, then the method is referred to as the ``HK
method''. 

Full details on how the model works are provided by  \citet{kamio10},
and we give a brief summary below:

\begin{itemize}
\item The model is based on measurements of the centroid of
  \ion{Fe}{xii} \lam195.12 line over the entire course of the Hinode
  mission. 
\item As new data are obtained, the model correction is continually
  updated.
\item The model sets the average \lam195.12 velocity over the whole
  mission to be 0~\kms, thus the spectrum drift correction also yields
  a form of absolute wavelength calibration.
\item Following the spectrum drift correction, centroids should be
  accurate to 4.4~\kms.
\item The data needed for performing the spectrum drift correction are
  stored in the EIS Solarsoft distribution. 
\end{itemize}

\section{How is the spectrum drift correction implemented?}

An empirical model has been developed to reproduce the drift of the
EIS spectrum using instrumental house keeping temperatures and the
relative motion of the spacecraft, see \citet{kamio10}.


The wavelength correction can be found using eis\_wave\_corr\_hk.pro, the
gethkwavecorr() method of the eis\_data object or eis\_prep.pro. All
procedures use specially prepared house keeping data files that are
distributed with SolarSoft in the directory \$EIS\_DATA/wave\_corr. If
the house keeping files that are needed for correcting a certain EIS
raster are missing in your SolarSoft installation, the new routines
will search for the files in \$EIS\_WAVE\_CORR\_HK\_DATA (if this
environment variable is set), and in the current working directory. If
the files are not found, they will automatically be downloaded from
the Oslo archive and saved in \$EIS\_WAVE\_CORR\_HK\_DATA (if set) or to
the current working directory (if not set). 

The following three examples demonstrate different methods to obtain the new wavelength correction. The example data-set is specified through
%
\begin{verbatim}
IDL> paths = '~/hinodedata/eis/mission/2007/12/11/eis_l0_20071211_162413.fits.gz'
\end{verbatim}
%
(please modify the path to the location where your Hinode data are stored).

\subsection{eis\_getwindata.pro}

This routine reads a specified wavelength window into an IDL
structure. By default it also calls the routine eis\_wave\_corr.pro
and stores the wavelength correction related to the spectrum drift
within the structure, in a tag called wave\_corr\_t. For example:
%
\begin{verbatim}
IDL> wd=eis_getwindata(paths,195.12)
IDL> help,wd.wave_corr_t
<Expression>    DOUBLE    = Array[256]
\end{verbatim}
%
This array gives the wavelength correction for each exposure in the
raster required to put the emission line on the absolute wavelength
calibration scale of the \citet{kamio10} method.

The windata structure has an additional tag called wave\_corr that
combines the spectrum drift with the EIS slit tilt (see EIS Software
Note \#4) to give a 2D array.

The wave\_corr array stored in the windata structure is used by the
Gaussian fitting routine eis\_auto\_fit.pro to perform the spectrum
drift and slit tilt corrections, so that the velocity map that results
from the fit is free from these instrumental effects.

\subsection{eis\_wave\_corr.pro}

The eis\_wave\_corr routine was modified in 2010 September so that it
uses the HK method by default. Previously it has used moments of the
\ion{Fe}{xii} \lam195.12 line to determine the spectrum drift. The
calling sequence is:
%
\begin{verbatim}
IDL> eis_wave_corr, paths, wvl_corr, dw_tilt, dw_t
\end{verbatim}
%
(the last two parameters are optional). To use the previous method to
determine wvl\_corr, set the /OLD keyword.

There is a routine called eis\_wave\_corr\_hk which returns wvl\_corr,
dw\_tilt and dw\_t in the identical manner to eis\_wave\_corr (in fact
it is called by eis\_wave\_corr)  but which has the additional two keywords:
%
\begin{description}
    \item[wvl\_cube:] If set to a named variable, wvl\_cube will return a 3 dimensional wavelength cube in the format used by mk\_analysis.pro of the Component Fitting System for IDL (cfit) package.
    \item[lam:] the underlying methods of eis\_data calculate the
    wavelength correction in pixels, and we assume that the shift in
    pixels is the same for all lines formed at any location on the two
    detectors. However, when measured in Angstroms the line centre
    variation and the slit tilt will vary slightly with wavelength. As
    default, eis\_wave\_corr\_hk assumes that the corrections are to be
    calculated for the Fe XII 195~\AA\ line, but the lam keyword may be
    set to the wavelength of the line you want to investigate. For
    example, the following code compares the spectrum drift for the Fe
    XII \lam195.12 and \ion{Fe}{xv} \lam284.16 lines.
\end{description}
%
\begin{verbatim}
IDL> eis_wave_corr_hk, paths, wvl_corr_hk, dw_tilt_hk, dw_t_hk
IDL> plot, dw_t_hk, /xst, /yst
IDL> eis_wave_corr_hk, paths, wvl_corr_hk2, dw_tilt_hk2, dw_t_hk2, 
             wvl_cube=wvl_cube, lam=284.16
IDL> help, wvl_cube
IDL> loadct,12 & oplot, dw_t_hk2, color=170 
\end{verbatim}
%
Finally, eis\_wave\_corr\_hk can take a level 0 or level 1 eis\_data
object reference as input instead of a file name: 
%
\begin{verbatim}
IDL> o = obj_new('eis_data',paths)
IDL> eis_wave_corr_hk, o, wvl_corr
\end{verbatim}

\subsection{gethkwavecorr(), a new eis\_data method}

When creating an eis\_data object, the aux\_data will contain two new
null pointers, hkpixcorrtilt and hkpixcorrtime: 

\begin{verbatim}
IDL> o = obj_new('eis_data',paths)
IDL> help, o->getaux_data(),/str
\end{verbatim}

The two pointers will become valid when the method gethkwavecorr() is
called (i.e. when you try to access the contents of the pointers): 

\begin{verbatim}
IDL> corr = o->gethkwavecorr()
IDL> help, corr,/str
IDL> help, o->getaux_data(),/str
\end{verbatim}

The gethkwavecorr() may be called with a wavelength as input parameter, or with the keyword wvl\_cube set, to get the same functionality as for the eis\_wave\_corr\_hk wrapper as explained above.

\begin{verbatim}
IDL> corr = o->gethkwavecorr(/wvl_cube)
IDL> help,corr,/str
IDL> corr = o->gethkwavecorr(284.16)
IDL> oplot,corr.time,color=0
\end{verbatim}

\subsection{eis\_prep.pro, with hkwavecorr set}

eis\_prep.pro now accepts the keyword hkwavecorr. If set, the resulting level 1 file will contain the wavelength correction information.

\begin{verbatim}
IDL> eis_prep,paths,outdir='~/',/hkwavecorr,/default,/quiet,/save
IDL> o = obj_new('eis_data','~/eis_l1_20071211_162413.fits')
IDL> help,o->getaux_data(),/str
IDL> corr = o->gethkwavecorr()
IDL> oplot,corr.time
\end{verbatim}


\begin{thebibliography}{}

\bibitem[Kamio et al.(2010)]{kamio10}
  Kamio, S., Hara, H., Watanabe, T., Fredvik, T. \& Hansteen, V. H.,
  2010, 
  Sol. Phys., 266, 209

\end{thebibliography}


\end{document}
