\documentclass[panstarrs]{panstarrs}

% basic document variables
\title{How to Define IPP Analysis Parameters}
\subtitle{A User's Guide}
\shorttitle{Defining IPP Parameters}
\author{Eugene A. Magnier}
\audience{IPP Users}
\group{Pan-STARRS Algorithm Group}
\project{Pan-STARRS Image Processing Pipeline}
\organization{Institute for Astronomy}
\version{XX}
\docnumber{PSDC-XXX-XXX}

% allow paragraphs to be listed in TOC for now 
\setcounter{tocdepth}{3} 

\begin{document}
\maketitle

% -- Revision History --
\RevisionsStart
% version     Date         Description
DR.01     & 2006.07.28 & First Draft \\ \hline
\RevisionsEnd

\tableofcontents
\pagebreak

% \listoffigures
% \pagebreak
\pagenumbering{arabic}

\section{Overview}

This Pan-STARRS IPP is a complex software system with many components.
It is very flexible, and may be configured to handle data from a wide
variety of sources.  The analysis programs have user-defined
parameters which need to be set appropriately for a given set of data.
Each camera, and in some cases each chip, may require slightly
different settings.  This document outlines the process by which these
parameters may be set and guidelines for which parts of the analysis
programs may require tweaks.

This document does not cover the setup of the IPP infrastructure.  The
way in which the analysis programs are interrelated and how to define
the tables used to track the data through the IPP is discussed in a
separated document (TBD).

The IPP performs a wide range of tasks, and consists of several
top-level programs.  Some of these programs (eg, ppImage) are used in
different contexts, and may require different parameter settings
depending on the context.  The recipe system allows these contexts to
be well-defined; please consult the relevant software design
descriptions for information on managing different recipes.  The
analysis program relevant to this document are listed in
Table~\ref{programs}.  Notice that certain programs (i.e.,
\code{psphot} and \code{psastro}) are available as stand-alone
programs and also a library calls within other programs.  The recipes
defined for one of these contexts may also be used by the other.

\begin{table}[ht]
\begin{center}
\caption{IPP Analysis Programs\label{programs}}
\begin{tabular}{lll}
\hline
\hline
{\bf IPP program} & {\bf Status}  & {\bf Function} \\
\hline
\code{ppMerge} 	  & completed     & Combine images for detrend creation (no warping) \\
\code{ppImage} 	  & completed     & General single-image analysis program \\
\code{ppStats} 	  & completed     & Report image statistics (from header and pixels) \\
\code{ppNorm} 	  & completed     & Perform normalization on detrend images \\
\code{psphot} 	  & completed     & Perform object detection and charaterization \\
\code{psastro} 	  & completed     & Perform astrometric calibration \\
\code{stac} 	  & prototype     & Warp and combine science images \\
\code{poisub} 	  & prototype     & Perform image differencing \\
\hline
\end{tabular}
\end{center}
\end{table}

\subsection{Detrend Creation}

The Detrend Creation portion of the IPP depends heavily on
\code{ppMerge} to build stacks of individual images.  In this section,
we discuss the issues which must be examined for each of the types of
detrend data to be created. 

\subsubsection{Bias Creation}

The bias creation tool (\code{ppMerge}) combines raw bias images into
a master stack.  The tool may use several possible statistics to
determine the value of an output pixel: mean and median, clipped
versions, and robust version.  The value of the clipping parameters,
if used must be set.  Decisions are primarily based on constructing
bias images from a set of raw biases and applying them back to the raw
bias imaes.  For any camera, following decisions must be taken:

\begin{itemize}
\item Is a bias image needed?  It can be skipped if a dark image is
  used and the bias is the same for all dark exposures.  It may also
  be skipped if the overscan subtraction is sufficient and
  sufficiently stable. 
\item Which combination statistic must be used?  The available options
  may be tried and the best one selected.  
\item Is it necessary to select the bias image on the basis of other
  camera parameters (detector temperature? readout mode?).  Note that
  these type of selections may be made by the detrend creation and
  application tools, but they are not provided by default: they will
  only be added to the tool if needed or if time permits before hand.
\item Is it necessary to reject raw bias images from the stack on the
  basis of other camera parameters (dome open/closed? detector
  temperature?).  Note that these type of selections may be made by
  the detrend creation tool, but they are not provided by default:
  they will only be added to the tool if needed or if time permits
  before hand.
\end{itemize}

\subsection{Dark Creation}

The dark creation tool (\code{ppMerge}) combines raw dark images into
a master stack.  The tool may use several possible statistics to
determine the value of an output pixel: mean and median, clipped
versions, and robust version.  The value of the clipping parameters,
if used must be set.  Decisions are primarily based on constructing
dark images from a set of raw darks and applying them back to the raw
dark images.  For any camera, following decisions must be taken:

\begin{itemize}
\item Is a dark image needed?  It can be skipped if there is
  insufficient dark current.
\item Which combination statistic must be used?  The available options
  may be tried and the best one selected.  
\item Is it necessary to select the dark image on the basis of other
  camera parameters (detector temperature? readout mode?).  Note that
  these type of selections may be made by the detrend creation and
  application tools, but they are not provided by default: they will
  only be added to the tool if needed or if time permits before hand.
\item Is it necessary to reject raw dark images from the stack on the
  basis of other camera parameters (dome open/closed? detector
  temperature?).  Note that these type of selections may be made by
  the detrend creation tool, but they are not provided by default:
  they will only be added to the tool if needed or if time permits
  before hand.
\item What is the scaling of a dark image by dark exposure time?  Is
  it necessary to have well-matched darks, or can a set of exposure
  times be chosen and interpolation used between these exposure times?
\end{itemize}

\subsection{Flat Creation}

The flat creation tool (\code{ppMerge}) combines raw flat images into
a master stack.  The tool may use several possible statistics to
determine the value of an output pixel: mean and median, clipped
versions, and robust version.  The value of the clipping parameters,
if used must be set.  Decisions are primarily based on constructing
flat images from a set of raw flats and applying them back to the raw
flat images.  For any camera, following decisions must be taken:

\begin{itemize}
\item Are skyflats or domeflats better?  Both must be generated and
  photometric analysis of observations of stars used to select between
  these options.  Both the spatial consistency and the source
  stability should be considered in making the decision.  Thus the
  residual images should be used to judge the flat-field quality as
  well. 
\item Which combination statistic must be used?  The available options
  may be tried and the best one selected.  
\item For skyflats, what restrictions should be placed on the input
  image?  (eg, time-from-sunset, sky flux level, mean image counts).
\item Is it necessary to reject raw flat images from the stack on the
  basis of other camera parameters (dome open/closed? detector
  temperature?).  Note that these type of selections may be made by
  the detrend creation tool, but they are not provided by default:
  they will only be added to the tool if needed or if time permits
  before hand.
\end{itemize}

\subsection{Fringe Creation}

The fringe creation tool (\code{ppMerge}) combines raw fringe images into
a master stack.  The tool may use several possible statistics to
determine the value of an output pixel: mean and median, clipped
versions, and robust version.  The value of the clipping parameters,
if used must be set.  Decisions are primarily based on constructing
fringe images from a set of raw fringes and applying them back to the raw
fringe images.  For any camera, following decisions must be taken:

\begin{itemize}
\item Are skyfringes or domefringes better?  Both must be generated and
  photometric analysis of observations of stars used to select between
  these options.  Both the spatial consistency and the source
  stability should be considered in making the decision.  Thus the
  residual images should be used to judge the fringe-field quality as
  well. 
\item if skyfringes are used, how many reference images are needed?
\item Which combination statistic must be used?  The available options
  may be tried and the best one selected.  
\item For skyfringes, what restrictions should be placed on the input
  image?  (eg, time-of-night, sky flux level, mean image counts).
\item Is it necessary to reject raw fringe images from the stack on
  the basis of other camera parameters (dome open/closed? detector
  temperature?).  Time relative to sunset is a default option, but
  other parameters must be added on an as-needed basis.
\end{itemize}

\section{Detrend Analysis Recipes}

A critical operation performed by the IPP is the application of the
master detrend images to the individual science images.  This is
performed by \code{ppImage} and is the core of the Phase 2 analysis
stage.  Many of the issues important for the application of the
detrend images have already been addressed in the detrend creation
section above.  In this section, we discuss the steps of the analysis
which may require inputs beyond those already discussed.

\subsection{Overscan correction}

For science images, we can correct the basic electronic offset (bias)
by measuring the value of the overscan region.  The overscan may be
used to determine a single value, a row-by-row vector, a spline fit, or a
polynomial fit.  Clipping ranges must also be chosen.  These decisions
are made by performing the overscan correction on bias images with
different options and determining which results in a better
correction.  

\subsection{OTA Convolution of Detrend Images}

For the OTA guided images, it is necessary to convolve the OTA kernel
with some of the detrend images.  It is necessary to decide which of
the images should be convolved.  The likely candidates are the
flat-field and the fringe images.  The bias and dark images do not
need to be convolved.  The flat images do.  The fringe images are less
clear.  If the fringe patterns consist of lower spatial frequencies
than the OTA kernel, then they may not need to be convolved.  The
convolution method (direct vs fft) must be tested as well; the choice
will depend on which is faster, which in-turn will depend on the
typical size of the convolution kerne.  Night-time science images are
needed to make this judgement.

\subsection{Non-Linear Correction}

The non-linearity of the devices must be measured.  This is the
responsibility of the Camera team.  The resulting function or lookup
table must supplied to the IPP and will be applied to the data.  The
choice to make here is how the non-linear correction is represented:
lookup table or interpolation function?

\section{Single-Image Photometry}

\subsection{PSF model function}

The PSF model function must be selected from the available models, or
a new model which better represents the available data supplied.  The
current design of PSPhot supplies a range of analytical models.  The
choice of which model to use, and the depends on the optical
parameters of the camera

\subsection{Sky Model Grid Scale} 

PSPhot constructs a global model for the large-scale variations in the
background to subtract before performing source detection and
characterization.  This model is built by measuring the median for
image pixels within large superpixels.  The size of the superpixels is
configurable and must be chosen based on the maximum allowed size of
the PSF and on the size of the smallest features which should be
subtracted. 

\subsection{Other PSPhot parameters}

A variety of minor PSPhot parameters must be tuned to meet both the
speed and the photometric accuracy requirements.  For example, the S/N
per pixel of the pixels included in a source fit, or the maximum
number of stars included in the measurement of the PSF model.  A
number of images from the camera representing the expected or allowed
range of seeing are required to choose these parameters.

\section{Astrometry}

\subsection{Initial Search Radius}

The astrometry analysis requires a search radius within which it will
search for matches between the reference stars and the observed
stars.  The size of this search radius will depend on the
repeatability of the telescope pointing.  The search radius should be
as small as possible yet still guarantee that the match will be made
for all images.

\subsection{Order of Fitting Functions}

The order of the polynomials used to represent the astrometry model
needs to be set based on the observed data.  The smallest order which
achieves the astrometric accuracy requirements should be used.  This
value will depend on the real properties of the distortion in the
images.  

\end{document}
