%+
% Name:
%    memo_acis_cc_calc_toa_4.3b.tex
%
% Usage:
%    latex memo_acis_cc_calc_toa_4.3b.tex
%
% Description:
%    This document describes the specification for acis_cc_calc_toa.
%
% Input:
%
% Output:
%
% Notes:
%
% History:
%    07 Dec 00, created, Glenn E. Allen
%    12 Dec 00, modified substantially--draft 2, GEA
%    19 Mar 01, added spec for dispersed events, GEA
%    20 Mar 01, modified to accommodate some of DPH's comments, GEA
%    02 Apr 01, added 2.9 s offset, GEA
%    24 Oct 01, removed grating information and changed to ape from
%       acis_cc_calc_toa, GEA
%    31 Oct 01, revised after a 26 Oct 01 meeting with Jonathan, Kenny, Joe,
%       and Liz, GEA
%    07 Apr 02, added SKY_1D, GEA
%    09 Sep 02, modified header, GEA
%-

\documentclass{article}

\usepackage{cxo-memo-logo}
\usepackage[dvips]{graphics}
\usepackage{gea}

\newcommand{\calccctimes}{calc\_cc\_times}
\newcommand{\ccdidi}{\ccdid_{i}}
\newcommand{\ccdidtargi}{\ccdid_{{\rm TARG}_{i}}}
\newcommand{\chipyi}{\chipy_{i}}
\newcommand{\chipytargi}{\chipy_{{\rm TARG}_{i}}}
\newcommand{\chipytargiminusone}{\chipy_{{\rm TARG}_{i-1}}}
\newcommand{\dec}{{\rm DEC}}
\newcommand{\deci}{{\rm DEC}_{i}}
\newcommand{\decnom}{{\rm DEC\_NOM}}
\newcommand{\ra}{{\rm RA}}
\newcommand{\rai}{{\rm RA}_{i}}
\newcommand{\ranom}{{\rm RA\_NOM}}
\newcommand{\roll}{{\rm ROLL}}
\newcommand{\rolli}{{\rm ROLL}_{i}}
\newcommand{\timeevtone}{{\rm TIME}_{{\rm evt}_{1}}}
\newcommand{\timeevti}{{\rm TIME}_{{\rm evt}_{i}}}

\begin{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 1. Header

\memobasic{
   Martin Elvis, SDS Group Leader }{
   Glenn Allen, SDS }{
   Computation of the Coordinates X, Y, and \skyoned\ and the Times of
      Arrival for Continuous-Clocking Event Data }{
   4.3b }{
   http://space.mit.edu/CXC/docs/docs.html\#toa }{
   /nfs/cxc/h2/gea/sds/docs/memos/memo\_acis\_cc\_calc\_toa\_4.3b.tex }

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 2. Introduction

\vspace*{0.3in} 
The event times in ACIS Level 0 continuous-clocking (CC) event-data files
are associated with the times events are read, not the times of arrival of
the particles that deposit charge in the detector. Therefore, analyses of
the event times to search for evidence of pulsations may be complicated by
the time it takes to read out an event, the motion of the source on the
detector as the telescope dither, the motion of the SIM relative to the
telescope, and the use of the gratings.  Analyses of the sky coordinates of
continuous-clocking mode event data can be difficult if the effects of
dither are not removed and if the source events are arbitrarily assumed to
have \chipy\ values of 512. To make it easier for users to analyze
continuous-clocking mode data, \ape\ should be modified (1) to compute the
times of arrival of events for a given source location, (2) to remove the
effects of dither and the SIM motion from the coordinates X and Y, (3) to
have an image of the coordinates X and Y pass throught the location
associated with \ratarg\ and \dectarg, and (4) to compute the coordinate
\skyoned (described below).  

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 3. ape

\section{\ape}

The tool \ape\ should create columns called \timero\ and \skyoned\ for
continuous-clocking event data.  The contents of the column \timero\
correspond to the times events are read (\ie\ are the same as the values of
\tim\ in Level 0 event files).  The contents of the column \tim\ are the
estimated times of arrival of events assuming the events are from a source
whose celestial coordinates are given by \ratarg\ and \dectarg.  Since it is
not possible to discriminate between events associated with the source and 
background events, all events are handled in the same manner.  The
coordinate \skyoned\ represents the distance of an event from the location
of the source (in arcseconds) in the direction perpendicular to the readout
direcion.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection*{Additional Parameters}

\begin{enumerate}

\item
\calccctimes,b,h,``no'',,,``Estimate the times of arrival for a CC-mode 
observation?''

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection*{Input}

\begin{enumerate}

\item
An ACIS continuous-clocking event-data file that includes the columns \tim\
(or \timero), \ccdid, and \chipx\ (or CCDX).  

\item
The associated aspect solution file.

\item
The right ascension (\ratarg) and declination (\dectarg) of the observed 
source in J2000.0 coordinates.  

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection*{Output}

\begin{enumerate}

\item
An ACIS event-data file that includes the columns \timero\ and \skyoned.

\item
If the value of the parameter \calccctimes\ is ``yes,'' the header of the
output file should contain the keyword HDUCLAS3 $=$ 'CC\_CORRECTED' to
confirm that the values in the column TIME are the estimated times of
arrival instead of the read-out times.  Otherwise, this keywords should be
excluded from the output file.

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection*{Processing}

\begin{enumerate}

\item
\label{step01}
Check for input errors: Verify that the input event files are 
continuous-clocking mode data files and contain columns named \tim\ (or
\timero), \ccdid, and CCDX (or \chipx).  Verify that the keywords \ratarg\
and \dectarg\ exist.  Verify that the input aspect solution file(s) exist.

\item
\label{step02} 
Read the values of the keywords \ratarg, \dectarg, \ranom, \decnom, and
\timedel\ from the header in the event data file.

\item
\label{step03}
Read the values of \ra, \dec, and \roll\ from the input aspect solution
file(s).

\item
\label{step04} 
Read the values of \tim, \timero\ (if it exists), \ccdid, CCDX (or \chipx),
and CCDY (or \chipy) for event $i$.  If the columns \chipx\ and \chipy\ do
not exist, compute the values of these coordinates.

\item
\label{step05} 
If the value of the parameter \calccctimes\ is ``yes'' and the column
\timero\ does not exist in the input file, copy the value of TIME for event
$i$ to the column \timero.  If the column \timero\ exists, do not copy the
value of TIME to \timero\ (even if \calccctimes\ $=$ ``yes'').  If
\calccctimes\ $=$ ``no'' and the column \timero\ exists, copy the value of
\timero\ for event $i$ to the column \tim.

\item
\label{step06}

Estimate the time of arrival of the event.  This estimate is to be used only
to compute the values of $\ccdidtargi$ and $\chipytargi$ associated with the
source location.  (See step~\ref{step5}.) The time of arrival that is
written to the output file is the time of arrival computed in
step~\ref{step6} below.  For the first event in the input event data file,
the estimated time of arrival 
%
\begin{equation}
t_{1} = \timero_{1} - (512 + 1028) \times \timedel,
\end{equation}
%
where $\timero_{1}$ is the read-out time of the first event.  For all 
subsequent events in the input file, the estimated times of arrival 
%
\begin{equation}
t_{i} = \timero_{i} - (\chipytargiminusone + 1028) \times \timedel,
\end{equation}
%
where $\timero_{i}$ is the read-out time of the $i^{\rm \/th}$ event and 
$\chipytargiminusone$ is the \chipy\ coordinate associated with the 
source location (\ratarg, \dectarg) at the time of arrival of the $i-1^{\rm 
th}$ event.  The value of $\chipytargiminusone$ is the value computed 
in step~\ref{step5}.

\item
\label{step07}
Compute the $\ccdidtargi$ and $\chipytargi$ location of the source (\ratarg,
\dectarg) on the ACIS detector using the aspect solution at the estimated
time of arrival of event $i$ ($t_{i}$). This computation of the value of
$\chipytargi$ for an event should include the effects of dither and the SIM
motion. The coordinate $\chipytargi$ is used to compute the values of the
coordinates X, Y, and \skyoned\ and to estimate the time of arrival of the
$i+1^{\rm th}$ event.  (See step~\ref{step4}.)

\item
\label{step08}
Use the values of $\ccdidtargi$ and $\chipytargi$ to determine the value of
$\chipyi$.

If the value of \ccdid\ for event $i$ ($\ccdidi$) is in the range 4--9, if
$4 \le \ccdidtargi \le 9$, and if $2 \le \chipytargi \le 1023$, then
%
\begin{equation}
\chipyi = \chipytargi.
\end{equation}
%
If $4 \le \ccdid \le 9$ and either $\ccdidtargi \le 3$ or $\chipytargi$ is
not in the range 2--1023 (or both), then
%
\begin{eqnarray}
\chipyi
   & = SIM ???
   & 512 - \nonumber \\
   &
   & a \sin \left( \rolli \right) \left( \rai - \ranom \right) 
      \cos \left( \decnom \right) + \nonumber \\
   &
   & a \cos \left( \rolli \right) \left( \deci - \decnom \right),
\end{eqnarray}
%
where $\rai$, $\deci$, and $\rolli$ are the values of $\ra$, $\dec$, and
$\roll$ that have been interpolated to the time $t_{i}$, $a \approx 4.192
\times 10^{6} $~pixels rad$^{-1}$ (\ie\ $360 / 2 \pi\ {\rm deg\ rad^{-1}}
\times 3600\ {\rm arcsec\ deg^{-1}} \div$ FP-1.1 ${\rm arcsec\ pixel^{-1}}$)
is the inverse of the ACIS plate scale, and FP-1.1 is an entry in the CALDB
file ``sky.''








\item
If the value of the parameter \calccctimes\ is ``yes,'' perform steps 
\ref{step2}--\ref{step9}.  Otherwise, do not compute the times of arrival of 
the events, do not create the column named \timero, and copy the input event 
TIMEs to the output column TIME.

\item
\label{step6}
Compute the time of arrival of event $i$:
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \begin{equation}

\[ \tim_{i} = \timero_{i} - (\chipytargi + 1028) \times \timedel. \]

% \end{equation}
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
Note that the contents of the column \tim\ are modified to contain the
estimated times of arrival instead of the read-out times.

\item
\label{step7}
Compute the X and Y coordinates of event $i$ using $\ccdid_{i}$, the 
coordinates $\chipx_{i}$ and $\chipytargi$, the time $\tim_{i}$ 
(as computed in step~\ref{step6}), and the aspect solution.  The resulting 
coordinates are free of the effects of dither and the motion of the SIM.  
The sky image is a thin (one or a few pixels wide) line that passes through 
the source location (\ratarg, \dectarg).  Jonathan McDowell has already 
developed the code to perform this computation.

\item
Repeat steps~\ref{step3}--\ref{step7} for each event in the input event data
file.

\item
\label{step9}
Copy the contents of the input event file to the output event file.  Add the
column \timero\ to the output file.  Add appropriate HISTORY keywords to the
output file if it does not exist in the input file.

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 4. Related Issues

\section{Related Issues}

\begin{enumerate}

\item
Ensure that the GTI boundaries are computed using the correct set of times.

\item
Create an ARD that contains the number 1028.

\item
Modify the parameter eventdef.

\item
Modify tg\_resolve\_events to compute the time of arrival offset for dispersed
events.

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 5. Acknowledgements

\section{Acknowledgements}

The development of the algorithms to compute the sky positions and times of 
arrival of the events relied heavily on the assistance of Ian Evans, Peter 
Ford, Kenny Glotfelty, David Huenemoerder, Jonathan McDowell, Herman Marshall, 
Joe Masters, Arnold Rots, Divas Sanwal, and Allyn Tennant.  Jonathan 
McDowell produced much of the code to compute the sky positions of the 
events and Herman Marshall and Allyn Tennant provided a great deal of help 
with the algorithm to compute the times of arrival.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 6. Footer

\vfill

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 7. Finish

\end{document}
