\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. 18}
\vspace{3mm}
\hrule
\noindent Version 1.2 \hfill 8 April 2015
\vspace{2mm}
\hrule

\begin{centerpage}

\begin{center}
{\Large\bf EIS data files and directory structure}\\
\mbox{}\\
\mbox{}\\
Peter Young\\
George Mason University\\
4400 University Drive\\
Fairfax, VA 22030\\
U.S.A.\\
\mbox{}\\
pyoung9@gmu.edu
\mbox{}\\
\end{center}

\end{centerpage}

\end{titlepage}

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

\section{Overview}

This document describes the filename formats for EIS data, and gives a
recommendation about how the files should be stored on a user's
computer.

Note that members of the EIS PI team institutes probably have access
to the complete set of level-0 data at these institutes, and so these
users should take care
in attempting to `ingest' data (Sect.~\ref{sect.ingest}).

\section{Types of EIS file}

EIS filenames have the form

\begin{verbatim}
eis_TT_YYYYMMDD_HHMMSS.fits
\end{verbatim}

TT gives the type of the file: `l0' for level-0, `l1' for
level-1, and `er' for level-1 error file. YYYYMMDD gives the year-month-day, e.g., `20101020' for
20-Oct-2010. HHMMSS gives the start time (UT) of the observation, e.g.,
`082654' for 08:26:54.  Users are strongly recommended \emph{not} to
rename the EIS files, however users are recommended to compress the
files with, e.g., gzip.

Usually within a day-or-so of the observations the EIS data will be
written to a \emph{quicklook} file. These files may not contain all of
the data and may contain incorrect information in the headers, thus
they should not be used for data analysis. The file type is the same
as level-0 files, i.e., `l0', but they are stored in a different
directory (see the following section). \emph{Quicklook files are
  generally only
  available to the EIS team.}

Usually within a few days of the observation a level-0 file will be
generated. This should be the definitive level-0 file, although
sometimes level-0 files are re-formatted at a later date when extra
data are recovered from the telemetry stream.

The level-1 file contains calibrated intensities and, unlike the
level-0 file, it is generated by the user with the Solarsoft IDL routine
EIS\_PREP. When EIS\_PREP is run with the keyword /SAVE it creates two
files with types `l1' and `er'. The former is the level-1 file while
the latter is almost identical except that the calibrated intensity
arrays are replaced with arrays containing the error on the intensity.

Note that the various Hinode data archives distribute \emph{only}
level-0 files. Users are expected to generate the level-1 files at
their own institute using EIS\_PREP.


\section{Directory structure}\label{sect.dir}

The recommended directory structure for storing EIS level-0 files is
as follows:

\begin{verbatim}
/hinode
   /sot
   /xrt
   /eis
      /level0
         /2010
            /01
            /02
               /01
               /02
      /level1
         /2010
            /01
            /02
               /01
               /02    
\end{verbatim}

where level-0 files for 1-Feb-2010 will be stored in the
/hinode/eis/level0/2010/02/01 directory. 

The IDL routine \verb|eis_ingest.pro| will automatically move a file
or set of files into this directory structure
(Sect.~\ref{sect.ingest}), but the user must first set up the correct
environment variables for pointing to the location of the data. See
the next section.


\section{Environment variables}

Users should define a top level environment variable called
`HINODE\_DATA' to point to the location of Hinode data on their
computer. This definition should be stored in either the user's .cshrc
(or equivalent)
file, or the IDL startup file. The examples below assume it is defined
in the IDL startup file.

\begin{verbatim}
setenv,'HINODE_DATA=/user/home/data/hinode'
\end{verbatim}

With this environment variable set, the EIS software will
automatically check for level-0 and level-1 files in the directories:

\begin{verbatim}
$HINODE_DATA/eis/level0
$HINODE_DATA/eis/level1
\end{verbatim}

These default locations for the  level-0 and level-1 files can be
over-ridden with the environment variables 
\verb|$EIS_L0_DATA| and \verb|$EIS_L1_DATA|. For example:

\begin{verbatim}
setenv,'EIS_L0_DATA /user/home/eis_l0'
setenv,'EIS_L1_DATA /user/home/eis_l1'
\end{verbatim}

The \verb|$EIS_L1_DATA| variable is useful if your institution
stores level-0 data in an institution-wide directory to which you
do not have write access to. The \verb|$HINODE_DATA| variable would
point to this directory, and \verb|$EIS_L1_DATA| can be used to point
to a directory on the user's computer that he/she does have write
access to..

An additional variable, \verb|$EIS_QL_DATA| is available for the
location of quicklook data.


\section{How to organize your EIS data}

\subsection{Hinode Science Data Centre Europe}

If you use this service (http://sdc.uio.no), then when you select your
data-sets and click the `Retrieve' button you will be provided with a tar
or zip file containing the data files. This file should be downloaded
to your \verb|$HINODE_DATA| directory, and unpacked there. The files
will unpack into the correct EIS directory structure as described in
Sect.~\ref{sect.dir}.

\subsection{The eis\_ingest routine}\label{sect.ingest}

If you have a list of files in a directory, then they can be moved
into the EIS data directory tree by doing

\begin{verbatim}
IDL> filelist=file_search('*.fits*')
IDL> eis_ingest, filelist
\end{verbatim}

The files will automatically be moved into appropriate level-0 or
level-1 directory. Quicklook files are not supported, however.

Note that files will not be moved if files of the same name (whether
compressed or uncompressed) already exist in the destination
directory. 

\section{Finding files}\label{sect.find}

With the EIS files correctly sorted into the directory structure given
in Sect.~\ref{sect.dir}, then the user can search for a file as
follows. For example,
%
\begin{verbatim}
IDL> file=eis_find_file('5-jan-2010 05:00')
\end{verbatim}
%
which will search for the nearest EIS level-0 file to the specified
time. The keyword /LEVEL1 allows the search to be performed on level-1
files. A complete list of files for the specified day can be obtained
by giving the /ALL keyword.

A useful option is /sequence which will return the names of all the
files in the sequence. For example, if the file at 05:00 on 5-Jan-2010
belongs to a sequence of files running between 01:00 and 08:00, then
all of these files will be returned. A sequence is a set of
raster-repeats. An example for using this keyword is:
%
\begin{verbatim}
IDL> file=eis_find_file('20-jan-2007 22:00',/sequence)
IDL> eis_raster_browser, file
\end{verbatim}
%


\newpage
\appendix

\section{Document modification history}

\noindent\emph{Version 1.2}: Added mention of the /sequence keyword in
Sect.~\ref{sect.find}. 

\noindent\emph{Version 1.1}: Added warning in introduction for users at
EIS PI institues; Sect.~\ref{sect.ingest} now states that files will
not be moved if they already exist in destination directory.

\end{document}