%+
% Name:
%   memo_random_0.3.tex
%
% Usage:
%    latex memo_random_0.3.tex
%
% Description:
%    This document describes required additions to header keywords
%       in order to accommodate non-pixel-randomized processing. 
%
% Input:
%
% Output:
%
% Notes:
%
% History:
%   24 February 04, created (v0.1), 
%   01 March    04, created (v0.2), 
%   01 March    04, created (v0.3), now including more details. 
%-

\documentclass{article}

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

\newcommand{\lsf}{LSFPARM}
\newcommand{\tgres}{tg\_resolve\_events}
\newcommand{\hpe}{hrc\_process\_events}
\newcommand{\apeb}{acis\_process\_events}
\newcommand{\apply}{apply\_tgain}

\begin{document}

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

% 1. Header

\memobasic{
   All those whom it may concern }{
   Bish K. Ishibashi, SDS }{
   Introducing New Keywords for Non-Pixel-Randomized Event files}{
   0.1 }{}{
   /nfs/cxc/h2/bish/CXC\ SDS/RANDOM/memo\_random\_0.3.tex}

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

% 2. Theme

\section{Pixel Randomization}

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

% 3. Description

\subsection{ Description }

Chandra's bore-sight shifts in Lissajous pattern by default. Through 
aspect processing, each event is mapped into a proper place and 
an aspect-corrected image is reconstructed. It is, however, noted earlier
that anomalous aliasing / artifacts remain in the aspect reconstructed image. 
In order to minimize the effect of potentially harmful artifacts, 
uniform pixel randomization of $\pm 0.5$~pix is applied onto CHIP X and Y 
prior to calculating SKY X and Y values. A similar spatial pixel 
randomization is applied in TG coordinate when processed through CIAO 
\tgres. In the same sense, another randomization is being added onto ACIS
energy (PHA) value. This is to mitigate PI spectral aliasing (PHA  
$\pm 0.5$~adu). 

\vspace{1mm}
\noindent
In Repro {\em{III}}, decisions have been made to alter some default options 
for randomization on SKY X/Y and TG R/D, while keeping the PI randomization
as it is. This document describes how we propose to implement additional 
keywords into Level 1 Event products and higher. 

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

% 4. Current Status

\subsection{ Data Randomization }

\noindent
Table~1 shows the current schema for data randomization and proposed changes. 
Both spatial and grating coordinate randomizations are applied onto CHIP X/Y
coordinates ($\pm 0.5$~pixels) when converting from CHIP to SKY or CHIP to 
TG coordinates. As for energy randomization, it is applied onto PHA value 
($\pm 0.5$~adu) when converting from PHA to ENERGY and then to PI. 

\begin{table}
  \begin{center}
    \begin{tabular}{lccl}
      \multicolumn{4}{c}{Table~1. Data Randomization } \\
      \hline
      \hline
      \
        Quantity & Present Default  & Proposed Default   & Comment \\
        \hline
        \\
        SKY X/Y (ACIS) & CHIP $\pm 0.5$~pix    & $\pm 0.5$~pix       & Need new development of SER scheme. \\
        SKY X/Y (HRC)  & CHIP $\pm 0.5$~pix    & 0.0~pix             & Randomization adds no merit. \\
        TG  R/D (ACIS \& HRC) & CHIP $\pm 0.5$~pix    & 0.0~pix      & No viable merit in randomization. \\
        \\
        PI energy (ACIS) & PHA  $\pm 0.5$~adu   & $\pm 0.5$~adu       & Mitigates PI spectral aliasing \\
        \\
      \hline
    \end{tabular}
  \end{center}
\end{table}


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

% 5. Request for enhancement

\subsection{ Required Additional Header Keywords }

\noindent
To define query expression for randomized or non-randomized calibration 
products in CALDB, we require additional header keywords to be defined and 
implemented into appropriate products (e.g., LSFPARM and gRMF) and processed 
event files at Level 1 (e.g., for SKY X/Y) or higher. To accommodate this 
enhancement, we propose to introduce the following three new keywords as 
``blessed'' (i.e., primary keywords to be carried over) entities (Table~2).


\begin{table}
  \begin{center}
    \begin{tabular}{lccl}
      \multicolumn{4}{c}{Table~2. New Keywords for Randomization } \\
      \hline
      \hline
      \
        Keyword    & Type    & Value       & Description \\
        \hline
        \\
        RAND\_SKY  & Float   & [0.0, 0.5]  & Sky X/Y randomization \\
        RAND\_TG   & Float   & [0.0, 0.5]  & Grating Coordinate randomization \\
        \\
        RAND\_PI   & Boolean & T/F         & This may not be necessary right now\\
        \\
      \hline
    \end{tabular}
  \end{center}
\end{table}


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

% 6. Tools

\section{ DS / CIAO Tools }

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

% 7. Affected tools

\subsection{ Affected CIAO tools }

\noindent
This enhancement will affect the following DS/CIAO items listed in Table 3.

[*** DS folks, please identify DS tools *** (TBD)] 


\begin{table}
  \begin{center}
    \begin{tabular}{lcl}
      \multicolumn{3}{c}{Table~3. Affected Tools } \\
      \hline
      \hline
      \
        Toolname        & Keywords           & Description \\
        \hline
        \\
        \ape\           & RAND\_SKY,RAND\_PI & controlled via rand\_pix\_size and rand\_pha \\
        \hpe\           & RAND\_SKY          & controlled via rand\_pix\_size \\
        \tgres\         & RAND\_TG           & controlled via rand\_pix\_size \\
        mkgrmf          & RAND\_TG           & query keyword to locate proper CALDB/LSFPARM \\
        ardlib          & RAND\_TG           & set query expression for mkgrmf \\
        hdrlib          & All                & acknowledge new keywords; accept new conditions \\
        merging\_rules  & All                & define new merging rules for dmmerge \\
        \\
      \hline
    \end{tabular}
  \end{center}
\end{table}

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

% 8. Parameter Strings / Change of input condition

\subsection{ Option for Data Randomization }

In CIAO version 3.0.2 or earlier, CIAO parameter ``rand\_pix\_size'' in 
\ape, \hpe, and \tgres\ allows users to specify any value between 0.0 and
0.5. This scheme is to be changed such that the allowed value for the 
parameter is either 0.0 or 0.5, controlled through parameter library 
(e.g., instead of setting the value [min,max]=[0.0,0.5], the argument 
for the parameter will become {0.0|0.5}, i.e., 0.0 or 0.5). This involves 
changes only in parameter files and not necessary to modify the existing 
subroutines for data randomization. 


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

% 9. 

\subsection{ Tools: \apeb, \hpe, \tgres\ and hdrlib }

Consult Kenny G. for the detail of requirement and code changes on these
tools. (TBD)

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

% 10.

\subsection{ Tools: mkgrmf / ardlib }

Consult John E.D. for the detail. 

\noindent
Simply taking the status of pixel randomization via RAND\_TG keyword from 
a file specified in the parameter ``obsfile'' and then allowing ardlib to 
embed the information into CALDB query expression, the correct LSFPARM 
product will be loaded into mkgrmf. The keyword RAND\_TG will be propagated
into grating RMF products. 

\vspace{2mm}
\noindent
In case where the keyword RAND\_TG does not exist in the obsfile (e.g, 
current archival datasets), prompt appropriate warning (e.g., ``RAND\_TG not found'') 
and then assume RAND\_TG = 0.5 to process. 

\vspace{2mm}

\noindent
In case where LSFPARM keywords in ardlib.par is set to CALDB and 
the keyword RAND\_TG is not set to either 0.0 or 0.5, then exit
gracefully with appropriate status code. 
\vspace{2mm}

\noindent
In case where LSFPARM keywords in ardlib.par is set to a specific file, 
then use the file to generate grating RMF. [Question: can the keyword
RAND\_TG be obtained from the LSFPARM file if exists, and if not exists, 
assume RAND\_TG value be 0.5? (TBD)]


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

% 11.

\subsection{ Merging Rules }

We propose the following merging rules for all RAND\_* keywords (Table~4).  

\begin{table}
  \begin{center}
    \begin{tabular}{ll}
      \multicolumn{2}{c}{Table~4. Merging Rules } \\
      \hline
      \hline
      \
        Condition       & Action              \\
        \hline
        \\
        Same keywords   & Merge \& propagate the keyword value \\
        Absent         & Issue warning, merge, but do not propagate the keyword \\ 
        Different       & Issue warning, merge, but do not propagate the keyword \\
        \\
      \hline
    \end{tabular}
  \end{center}
\end{table}

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

% 11.

\section{ CALDB }

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

% 12.

\subsection{ Affected CALDB products }

CALDB products that are affected by the introduction of new randomization
keywords are listed in Table~5. 

\begin{table}[b]
  \begin{center}
    \begin{tabular}{lcl}
      \multicolumn{3}{c}{Table~5. Affected CALDB files } \\
      \hline
      \hline
      \
        CAL type        & Keyword            & Comment \\
        \hline
        \\
        LSFPARM         & RAND\_TG           & Currently only product with RAND\_TG=0.5 available \\
        GRMF            & RAND\_TG           & Not generally queried by CALDB interface \\
        \\
      \hline
    \end{tabular}
  \end{center}
\end{table}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}


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

% 8. Finish

\section{ Additional Remarks on Grating Coordinate Randomization }

\noindent
Currently we have an infrastructure that allows users to choose between 
randomized and non-randomized grating coordinate LSFPARM. This is to 
interact with ardlib manually by specifying what LSFPARM products to 
use. However, the use of keywords will make it more user-friendly. 


\end{document}

