\documentclass[11pt,fleqn]{article}

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

\usepackage[nochapter]{vhistory}
\usepackage{url}

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

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

\renewcommand{\textfraction}{0.05}
\renewcommand{\topfraction}{0.8}
\renewcommand{\bottomfraction}{0.8}

%% ----------------------------------------------------------------------
%% 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{}}

\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. 20}
\vspace{3mm}
\hrule
\noindent Version \vhCurrentVersion \hfill \vhCurrentDate
\vspace{2mm}
\hrule

\begin{centerpage}

\begin{center}
{\Large\bf EIS/AIA Coalignment}\\
\mbox{}\\
\mbox{}\\
John Mariska\\
George Mason University\\
College of Science\\ 
4400 University Drive\\
Fairfax VA 22030\\
USA\\  
\mbox{}\\
\verb+jtmariska@gmail.com+\\
\mbox{}\\
\end{center}

\end{centerpage}

\end{titlepage}

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

\section{Overview}

Now that SDO data are routinely available at a high cadence,
analyses of EIS data often include coalignment of EIS
spectroheliograms with AIA images. In addition data from the IRIS
satellite also require coalignment with EIS data sets and, of
more importance, joint observations will require knowledge of the
relationship between the EIS coordinate system and the IRIS
coordinate system.

Typically users of EIS data coalign their observations with AIA
on an ad hoc basis, either simply visually adjusting the EIS
image or applying one of several cross-correlation programs
designed for that purpose. This document reports on a systematic
investigation of the relationship between the solar coordinate
system provided in the EIS level 0 data files and the solar
coordinate system provided in the AIA level 1 data files. The
result of the analysis is an IDL function for predicting the
time-dependent coordinate offsets between EIS and AIA. The
resulting corrections have been implemented as user options in
the EIS planning software.

\section{Data Selection and Analysis}

In 2012 May, the EIS team initiated a regular program of taking
slot images at Sun center during one or more of the daily XRT
synoptic observations. Data in both the 40 arcsec slot (EIS Study
354, PRY\_slot\_contextLITE) and the 266 arcsec slot were
routinely acquired. This analysis includes all the useful 40
arcsec slot data. Each data set was first processed using
EIS\_PREP. Using the DATE\_OBS and DATE\_END keywords in the
resulting level 1 FITS files, the VSO AIA database was queried
for full resolution AIA 193~\AA\ images taken during the time of
the EIS observations. Typically 14 or 15 data sets were
available. The VSO\_GET IDL function was then used to retrieve
the middle image of the set.

For each EIS data set the analysis followed the same procedure:
\begin{enumerate}

\item
The level 1 195~\AA\ image was retrieved Using EIS\_READSLOT and
solar coordinate arrays were constructed using the appropriate
FITS keywords.

\item
A margin of 70 arcsec was added on all sides of the coordinate
ranges and the $x$- and $y$-limits were used to extract a region
from the AIA image.

\item
The AIA subimage was resampled to the EIS pixel size using
CONGRID and new $x$ and $y$ AIA coordinate arrays were
constructed.

\item
Using the SSW KORREL function, the two images were used to
determine the $x$- and $y$-offsets necessary to bring them into
alignment.

\end{enumerate}

Figure~\ref{fig:sample_image} shows an example of the results of
this analysis. The left panel shows the EIS slot raster taken on
2012 August 4 beginning at 06:02:19 UT. The coordinate system on
the figure was produced using the keywords in the EIS FITS file.
The right panel shows the AIA image taken at 06:03:42 after it
has been resampled to the EIS pixel size. The coordinate system
on the figure was produced using the keywords in the AIA FITS
file. The dashed-line box on the AIA figure shows the location of
the EIS raster based on the coordinates in the EIS data file. The
solid-line box shows the EIS raster location that results from
using the output of the KORREL function to adjust the EIS
coordinates. In this case the shift required is $+9.0$ arcsec in
$x$ and $+14.2$ arcsec in $y$. If the analysis is repeated with
different margins for the AIA region, the results are generally
the same to within 1 arcsec.
\begin{figure}[t!]
\centering
\includegraphics[width=\textwidth]{figures/sample.eps}
\caption{EIS and AIA data showing the shift required to coalign
  the two data sets.\label{fig:sample_image}}
\end{figure}

Figure~\ref{fig:all_offsets} shows the offsets computed in this
manner for all the available EIS data sets. Positive numbers mean
that the values must be added to the EIS coordinate for it to
agree with the AIA coordinate. Both the $x$ and $y$ data sets
appear to have roughly the same scatter---about 5 arcsec. Since
repeated coalignments with the same data sets are good to about 1
arcsec, this scatter is probably showing the inherent variations
due to fluctuations of spacecraft pointing. The results cover
more than two years of systematic observation and show that the
general pattern of the fluctuations in pointing offsets repeats
year to year. In the $y$ coordinate, the largest excursion is
clearly centered on the annual Hinode eclipse season, which
begins in May and lasts until September. In the $x$ coordinate
the variations are more complex, with the largest excursion in
December. The dashed red lines in the figure mark the dates of
EIS heater setting changes. These changes noticeably impact both
the $x$ and $y$ coordinate variations.

Figure~\ref{fig:overlap} shows all the data averaged in
five-day bins and then plotted as a function of the day of the
year. This demonstrates that the yearly pattern repeats with only
minor variations and suggests that it should be possible to
develop software to predict the offsets for any day of the year.
\begin{figure}[t!]
\centering
\includegraphics[width=5.0in]{figures/coalign.eps}
\caption{Offsets between EIS and AIA as a function of
  time.\label{fig:all_offsets}}
\end{figure}

\begin{figure}[t!]
\centering
\includegraphics[width=5.0in]{figures/overlap.eps}
\caption{Averaged offsets between EIS and AIA as a function of
  day of year.\label{fig:overlap}}
\end{figure}

%%\begin{figure}[t!]
%%\centering
%%\begin{minipage}{0.45\textwidth}
%%\includegraphics[width=3.1in]{figures/coalign.eps}
%%\end{minipage}
%%\quad
%%\begin{minipage}{0.45\textwidth}
%%\centering
%%\includegraphics[width=3.1in]{figures/overlap.eps}
%%\end{minipage}
%%\caption{Offsets between EIS and AIA as a function of
%%  time.\label{fig:all_offsets}}
%%\end{figure}

\section{Predicting Coordinate Offsets}

Based on the apparent year-to-year reproducibility of the $x$ and
$y$ offsets, the best approach to predicting them is to construct
a table of averaged offsets and then use an IDL function to
interpolate into the table for any desired date. That is the
approach that has been implemented.

The current table was constructed by binning all the offset
measurements made from 2012 May 1 to 2015 May 1 into 73 five-day
date bins. This size is sufficient to capture enough data to
provide useful values in each bin, yet small enough to display
properly the trends in the data. Comparison of the five-day
averaged data with the interpolated values showed a small secular
variation in the residuals, which has been accounted for by
fitting the residuals with straight lines. Thus for any given
date the process of computing the offsets consists of
interpolating in the table and the applying the small additional
correction for the secular trend. This process has been
implemented as IDL function EIS\_AIA\_OFFSETS, which is located
in \$SSW/hinode/eis/idl/atest/mariska in the SolarSoft
distribution. The needed interpolation file,
eis\_aia\_yearly\_average\_v3.txt is stored in
\$SSW/hinode/eis/data/eis\_aia\_offset. That directory also
contains plots showing the performance of the software over
roughly a one year interval. Also included are current versions
of the plots in shown in Figure~\ref{fig:all_offsets}. All the
plots are updated several times a week as new coalignment studies
are processed.

Figure~\ref{fig:predictions_resid} shows a comparison between
recent five-day averaged data and the model predictions. The
predicted offsets represent the data well with the residuals
generally less that $\pm5$ arcsec.

\section{Using Coordinate Offsets for Observation Planning and
  Data Analysis}

\begin{figure}[t!]
\centering
\includegraphics[width=6.0in]{figures/predictions_resid.eps}
\caption{Averaged offsets between EIS and AIA as a function of
  time compared with predicted offsets based on averaging three
  years of measurements.\label{fig:predictions_resid}}
\end{figure}

With EIS often participating in observations with IRIS and also
ground-based observatories, there is increased need for EIS
planners both to place EIS observations in positions dictated by
other instruments and to give positions of EIS observations in
the solar coordinate systems used by other instruments. The
computed offsets necessary to shift the EIS coordinate system to
the AIA, and presumably IRIS, coordinate system can be used in a
number of ways. This section summarizes the relationships among
the EIS, SOT, and AIA coordinate systems. The relationships
outlined here have been implemented as options in the EIS
planning software.

In this section

\begin{itemize}

\item $\textrm{EIS\_coord}$ are the EIS coordinates provided in
  the EIS planning software.
 
\item $\textrm{AIA\_coord}$ is the AIA coordinate system provided
  in their level 1 data files. This document assumes that IRIS
  uses the same coordinates.

\item $\textrm{SOT\_coord}$ are the coordinates provided by the
  SOT team at planning meetings. Aside from special cases
  mentioned below, they are the same as AIA\_coord.

\item $\textrm{pointing\_file\_coord}$ are the coordinates in the
  Hinode pointing files.

\end{itemize}

Assuming that IRIS and AIA coordinates are the same, we have four
cases the EIS planner may need to consider:

\begin{enumerate}

\item The planner has planned an observation, has an EIS pointing
  at a specific time, and wants to communicate that to IRIS.
  \begin{equation}
    \textrm{AIA\_coord} = \textrm{EIS\_coord} +
    \textrm{shift\_from\_table}
   \end{equation}

where $\textrm{shift\_from\_table}$ comes from IDL function
EIS\_AIA\_OFFSETS.

\item The planner has been provided with an IRIS pointing at a
  specific time and wants to position EIS there.
  \begin{equation}
    \textrm{EIS\_coord} = \textrm{AIA\_coord} -
    \textrm{shift\_from\_table}
  \end{equation}

\item The planner has been provided coordinates by SOT. The
  coordinates provided by SOT are good in absolute terms. So we
  have
  \begin{equation}
    \textrm{EIS\_coord} = \textrm{SOT\_coord} -
    \textrm{shift\_from\_table}
  \end{equation}

In this case, EIS would report the $\textrm{SOT\_coord}$ to IRIS
as the EIS pointing.

\item The planner is using pointing coordinates from the pointing
  file and wants to place EIS at the same location that SOT is
  observing---IRIS takes care of itself. SOT is offset from the
  Hinode spacecraft pointing. Get the latest values for this
  correction by doing
  \begin{description}
    \item[\quad] grep SBOPS\_SC /home/flare/slb/sotco/.cshrc
  \end{description}
on EISCO. This currently (2014-Aug-1) outputs
    \begin{description}
      \item[\quad] setenv SBOPS\_SC\_XCORR 24
      \item[\quad] setenv SBOPS\_SC\_YCORR 15
    \end{description}
These values are also available at the daily planning meeting. In
the Hinode pointing tool underneath the tracking curve
definitions they are listed as ``Offset of SOT from Hinode.''
Finally, we have:
   \begin{eqnarray}
     \textrm{EIS\_coord} & = &\textrm{SOT\_coord} -
     \textrm{shift\_from\_table} \nonumber \\ 
     & = &
     (\textrm{pointing\_file\_coord} + \textrm{SOT\_correction})
     - \textrm{shift\_from\_table}
    \end{eqnarray}
Note that the SOT planner sometimes shifts the FOV on the CCD. To
attain the highest accuracy, consult the SOT CO.

\end{enumerate}
If EIS wanted to communicate its pointing to IRIS, it would
report it using the equation in case 1 above.

In the EIS planning software, the first case is the default. The
second case corresponds to the case listed as EIS aligned with
AIA, and the fourth case corresponds to the case EIS aligned with
AIA and SOT. For that case, there is a pull-down menu available
to allow entry of the latest SOT offsets. The EIS Observing
Timeline web page
(\url{http://solar-b.nrl.navy.mil/cgi-bin/timeline.cgi}) contains
a column that shows which pointing option the planner selected
for each study placed on the timeline. In addition the summary
text file produced by the planning software provides information
on the pointing option used for each timeline entry.

\section{Automated Updating of Offset Data}

While the yearly variations in the EIS pointing relative to the
AIA coordinate system generally repeat, there is some evidence
for gradual changes over longer time periods. Thus, additional
data will need to be acquired and analyzed on a regular basis.
The necessary observations are generally made during the regular
XRT synoptic observations. Analysis of those data is managed
using a cron task that runs on magnolia.nrl.navy.mil. Once each
day this task searches the EIS asrun catalog for all recent
occurrences of EIS study 354 that have been made near Sun center
and produces level 1 data files for any observations that have
not yet been processed. The software then identifies and
downloads AIA data for each EIS file, does the coalignment,
appends the offset information to a text file, and updates the
offset information in the Oslo EIS Subversion software
repository. The resulting data files and plots are in the
directory \$SSW/hinode/eis/data/eis\_aia\_offset.

A few times a year, the averaged data file will be regenerated
using added EIS data. That data file is currently version 2 and
uses two full years of observations. The IDL function that
computes offsets for any given date automatically finds the
highest version number of the file.

The plots of all the offset data in Figure~\ref{fig:all_offsets}
show some discontinuities when the EIS heater settings are
changed. To the extent it is possible, making those heater
changes close to the same dates each year will improve the
accuracy of the averaged data table that EIS\_AIA\_OFFSETS uses
to compute values. In one case, the September heater changes were
made at a different time from other years, resulting in the
differences visible in the $x$- offsets shown in
Figure~\ref{fig:overlap}. To allow anaysis of EIS data obtained
in that interval, the EIS\_AIA\_OFFSETS function contains logic
to modify the offsets in that interval.

\newpage
\appendix
\section{Revision History}

\begin{versionhistory}
  \vhEntry{1.0}{2014 Aug 25}{John Mariska}{Creation}
  \vhEntry{1.1}{2015 Jan 14}{John Mariska}{Minor revisons and
    update figures}
  \vhEntry{1.2}{2016 Mar 17}{John Mariska}{Minor revisons and
    update figures}
\end{versionhistory}

\end{document}

Some saved text in case we want to add an appendix showing the
table creation in more detail.

The attached figure outlines the approach. The top plots show all
the data we have taken since 2012 May 1 averaged into 5-day bins.
Overplotted on that in red is the predicted value based on simply
using that data to build a table of offsets versus time of year.
To get the red curve, one simply converts the date into a
fraction of a year and goes into an interpolation table to get
the predicted offsets. The middle plots show the residuals for
that fit. Note that the residuals show a small secular trend, I
would think due to the evolving orbit. The green lines on the
residual plots are a least-squares fit to the residuals. The
green lines on the top plots show the fit produced by using the
interpolation table and then adding the secular trend. Finally,
the bottom residuals plots show that the residuals are now
scattered around unity. My impression is that the resulting
offsets are good to +/- 2.5 arcsec.
