\documentclass[11pt]{article}

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

%% ----------------------------------------------------------------------
%% 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.
\setlength{\parindent}{0pt}

\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}$}
\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. 25}
\vspace{3mm}
\hrule
\noindent Version 1.0 \hfill 31 July 2020
\vspace{2mm}
\hrule

\begin{centerpage}

\begin{center}
{\Large\bf How to search for and download EIS files from IDL}\\
\mbox{}\\
\mbox{}\\
Peter Young\\
NASA Goddard Space Flight Center\\
Greenbelt, MD 20771\\
U.S.A.\\
\end{center}

\end{centerpage}

\end{titlepage}

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

\section{Overview}

This document describes how to search the EIS archives for specific
types of data and then download the files to your machine, all by
using IDL commands.


\section{Before you start}

The software makes use of the routine \verb|eis_ingest| to automatically put
the downloaded EIS files into an organized directory tree. Please
check out Sect.~4 of EIS Software Note No.~18 for how to set IDL
environment variables so that the ingestion process works correctly. 

\section{Searching for EIS data}

The key IDL routine to use is \verb|eis_obs_structure|, which was
briefly described in EIS Software Note No.~19. It returns an IDL
structure containing metadata about the EIS files that match the query
parameters.

There are two basic ways of using the routine: (1) by time, and (2) by
raster acronym. The first is:
%
\begin{verbatim}
IDL> s=eis_obs_structure(t0,t1)
\end{verbatim}
%
where t0 and t1 are times given in any standard Solarsoft format. The
structure will contain information about all EIS data-sets obtained
between the two times.

The second call is:
%
\begin{verbatim}
IDL> s=eis_obs_structure(rast_acr=rast_acr)
\end{verbatim}
%
where \verb|rast_acr| is the raster acronym. \emph{Be aware that the
  raster acronym is not the study acronym!} A study consists of one or
more rasters, although mostly it will be a single raster. If you know
the study acronym, then do:
%
\begin{verbatim}
IDL> eis_xstudy
\end{verbatim}
%
which will bring up a GUI listing all of the EIS studies. If you
select a study, then the window at the bottom of the GUI will now show
the rasters for that study. The window will display the raster
acronym. It is this acronym which needs to be input to
\verb|eis_obs_structure|. 

(\verb|eis_obs_structure| also has the optional input \verb|study_acr=|
for inputting the study acronym but this is much, much slower due to
how the EIS databases are structured.)

Try setting \verb|rast_acr=atlas_60|, which searches for one of the
EIS spectral atlas studies that is run regularly. Despite searching
the entire EIS database, you will notice that the call is very fast.

The structure output by \verb|eis_obs_structure| is an array, with one
entry for each raster. For example, the EIS planner may have scheduled
a study (consisting of a single raster) to run at 10:00~UT, and
specified that the study is repeated 20 times. This results in 20
rasters. The output from \verb|eis_obs_structure| for this observation
will be a structure array of 20 elements.

\section{Additional search filtering}

Once the observation structure has been created by
\verb|eis_obs_structure|, you can perform additional filtering with
the routine \verb|eis_filter_obs_struc|. Some examples are:
%
\begin{verbatim}
IDL> s2=eis_filter_obs_struc(s,/narrow)
IDL> s2=eis_filter_obs_struc(s,slit_index=1)
IDL> s2=eis_filter_obs_struc(s,xcen=[-200,200])
IDL> s2=eis_filter_obs_struc(s,ycen=[800,1100])
\end{verbatim}
%
The first keeps only narrow slit data (i.e., the 1'' and 2'' slits);
the second keeps the 266'' slot data\footnote{The EIS slits have
  indices 0,1,2,3 corresponding to the 1'',266'',2'' and 40'' slits.};
the third keeps only rasters with xcen values between -200 and 200;
and the fourth keeps only rasters with ycen values between 800 and
1100.

Perhaps the most powerful filter is for wavelength. For example:
%
\begin{verbatim}
IDL> s2=eis_filter_obs_struc(s,wvl=[184.54,275.36])
\end{verbatim}
%
will return only those rasters that contain both the \ion{Fe}{x}
\lam184.54 and \ion{Si}{vii} \lam275.36 emission lines. Note that this
checks if any of the wavelength windows contain these lines. For
example, if a window extends from 184.50 to 186.50~\AA\ then it will be
flagged even though the \lam184.54 line is right at the edge of the window.


\section{Download the files}

Once you have filtered the observation structure, you can then
download the files from the VSO by doing:
%
\begin{verbatim}
IDL> eis_vso_download_files,s
\end{verbatim}
%
This routine calls \verb|eis_ingest| to correctly place the files in
your EIS data directory tree.


\newpage
\appendix

\section{Document modification history}

\emph{Version 1.0, 31-Jul-2010}: First version.


\end{document}