Index: /trunk/doc/release.2015/ps1.analysis/analysis.tex
===================================================================
--- /trunk/doc/release.2015/ps1.analysis/analysis.tex	(revision 39844)
+++ /trunk/doc/release.2015/ps1.analysis/analysis.tex	(revision 39845)
@@ -410,5 +410,5 @@
 The variance image, if not supplied is constructed by default from the
 flux image using the configuration supplied values of \code{GAIN} and
-\code{READ\_NOISE} to calculate the appropriate Poisson statistics for
+\code{READ_NOISE} to calculate the appropriate Poisson statistics for
 each pixel.  In this case, the image is assumed to represent the
 readout from a single detector, with well-defined gain and read noise
@@ -444,5 +444,5 @@
 image.  The background image and the background standard deviation
 image are kept in memory from which the values of \code{SKY} and
-\code{SKY\_SIGMA} are calculated for each object in the output catalog.
+\code{SKY_SIGMA} are calculated for each object in the output catalog.
 
 \subsection{Initial Object Detection}
@@ -458,6 +458,6 @@
 the covariance, if known. At this stage, the goal is only to detect
 the brighter sources, above a user defined S/N limit (configuration
-keyword: \code{PEAKS\_NSIGMA\_LIMIT}).  A maximum of
-\code{PEAKS\_NMAX} are found at this stage.  The detection efficiency
+keyword: \code{PEAKS_NSIGMA_LIMIT}).  A maximum of
+\code{PEAKS_NMAX} are found at this stage.  The detection efficiency
 for the brighter sources is not strongly dependent on the form of this
 smoothing function.
@@ -546,5 +546,5 @@
 {\em key col} for this peak (as used in topographic descriptions of a
 mountain).  If the key col for a given peak is less than
-\code{FOOTPRINT\_CULL\_NSIGMA\_DELTA} (4.0) sigmas below the peak of
+\code{FOOTPRINT_CULL_NSIGMA_DELTA} (4.0) sigmas below the peak of
 interest, the peak is considered to be {\em locally insignificant} and
 removed from the list of possible detections.  In the vicinity of a
@@ -581,9 +581,9 @@
 to find a value of $\sigma_W$ for which $f$ is expected to be 0.65.
 \note{what is the expected ratio of $\sigma_x$ to the true value?}.
-We call this value the \code{MOMENTS\_GAUSS\_SIGMA}.  We use an
-aperture with a radius of \code{PSF\_MOMENTS\_RADIUS} = 4$\times$
-\code{MOMENTS\_GAUSS\_SIGMA} to select the pixels for the measurement.
-
-Once \code{PSF\_MOMENTS\_SIGMA} has been determined, moments are
+We call this value the \code{MOMENTS_GAUSS_SIGMA}.  We use an
+aperture with a radius of \code{PSF_MOMENTS_RADIUS} = 4$\times$
+\code{MOMENTS_GAUSS_SIGMA} to select the pixels for the measurement.
+
+Once \code{PSF_MOMENTS_SIGMA} has been determined, moments are
 measured as defined below.  
 
@@ -615,5 +615,5 @@
 
 If the measured centroid coordinates ($x_0, y_0$) differs from the
-peak coordinates be a large amount (\code{MOMENT\_RADIUS}), then the
+peak coordinates be a large amount (\code{MOMENT_RADIUS}), then the
 peak is identified as being of poor quality and is rejected.  In
 both of these cases, it is likely that the `peak' was identified in a
@@ -638,6 +638,6 @@
 limited at the low and high ends by $R_{\rm min} < M_r < R_{\rm max}$
 where $R_{\rm min}$ is the first radial moment of the PSF stars, or
-0.75$\times$ \code{MOMENTS\_GAUSS\_SIGMA} if that cannot be
-determined.  $R_{\rm max}$ is set to \code{PSF\_MOMENTS\_RADIUS}, the
+0.75$\times$ \code{MOMENTS_GAUSS_SIGMA} if that cannot be
+determined.  $R_{\rm max}$ is set to \code{PSF_MOMENTS_RADIUS}, the
 size of the moments aperture.
 
@@ -731,5 +731,5 @@
 registered as part of the model function code.  Another function is
 then used to return the appropriate function for a specific model
-type.  For example, the \code{psModelLookup\_GetFunction} will return
+type.  For example, the \code{psModelLookup_GetFunction} will return
 the \code{psModelLookup} function for a given model type.  This
 mechanism makes it very easy to add new model functions into the
@@ -756,5 +756,5 @@
 their peaks, as well as an approximate signal-to-noise ratio.  All
 objects with a S/N ratio greater than a user-defined parameter
-(\code{PSF\_SHAPE\_NSIGMA} ???) are selected by PSPhot, though objects
+(\code{PSF_SHAPE_NSIGMA} ???) are selected by PSPhot, though objects
 which have more than a certain number of saturated pixels are excluded
 at this stage.  PSPhot then examines the 2-D plane of $\sigma_x,
@@ -1014,5 +1014,5 @@
 
 PSPhot will use the user-selected galaxy model to attempt the galaxy
-model fits.  In the configuration system, the keyword \code{GAL\_MODEL}
+model fits.  In the configuration system, the keyword \code{GAL_MODEL}
 is set to the model of interest.  All suspected extended objects are
 fitted with the model, allowing all of the parameters to float.  The
@@ -1146,7 +1146,7 @@
 value for the ApResid scatter is then used by PSPhot as the best PSF
 model for this image.  The number of models to be tested is specified
-by the configuration keyword \code{PSF\_MODEL\_N}.  The configuration
-variables \code{PSF\_MODEL\_0}, \code{PSF\_MODEL\_1}, through
-\code{PSF\_MODEL\_N - 1} specify the names of the models which should be
+by the configuration keyword \code{PSF_MODEL_N}.  The configuration
+variables \code{PSF_MODEL_0}, \code{PSF_MODEL_1}, through
+\code{PSF_MODEL_N - 1} specify the names of the models which should be
 tested.
 
@@ -1198,13 +1198,14 @@
 
 The surface brightness values are sampled at a number of radial
-annuli, with the radii defined in the configuration ({\tt
-  RADIAL.ANNULAR.BINS.LOWER \& RADIAL.ANNULAR.BINS.UPPER}).  For each
-source, the resulting surface brightness profile is saved in the
-output cmf-file as an N-element value in the FITS table ({\tt
-  PROF\_SB}).  The flux at each radial position and the fill-factor
-(fraction of pixels used to the total possible) as also saved as
-equal-length vectors in the FITS table ({\tt PROF\_FLUX and
-  PROF\_FILL}).  The values of the radial bins are saved in the cmf
-header ({\tt RMIN\_NN, RMAX\_NN}).
+annuli, with the radii defined in the configuration
+(\code{RADIAL.ANNULAR.BINS.LOWER} \&
+\code{RADIAL.ANNULAR.BINS.UPPER}).  For each source, the resulting
+surface brightness profile is saved in the output cmf-file as an
+N-element value in the FITS table (\code{PROF_SB}).  The flux at each
+radial position and the fill-factor (fraction of pixels used to the
+total possible) as also saved as equal-length vectors in the FITS
+table (\code{PROF_FLUX} and \code{PROF_FILL}).  The values of the
+radial bins are saved in the cmf header (\code{RMIN_NN},
+\code{RMAX_NN}).
 
 \note{these profiles are not saved in PSPS}
Index: /trunk/doc/release.2015/ps1.calibration/calibration.tex
===================================================================
--- /trunk/doc/release.2015/ps1.calibration/calibration.tex	(revision 39844)
+++ /trunk/doc/release.2015/ps1.calibration/calibration.tex	(revision 39845)
@@ -22,8 +22,8 @@
 
 % Pick a terse version of the title here;
-\shorttitle{Pixel Analysis in PS1}
+\shorttitle{PS1 Calibration}
 \shortauthors{E.A. Magnier et al}
 \begin{document}
-\title{Pan-STARRS Pixel Analysis : Source Detection \& Characterization}
+\title{Pan-STARRS Photometric and Astrometric Calibration}
 
 % this is a crude trick to get the order of affiliations right.  These
@@ -194,24 +194,5 @@
 images.
 
-\section{Astrometric Model in PSASTRO} 
-
-\code{pasastro} loads the coordinates and calibrated magnitudes of
-stars from the reference database.  A model for the positions of the
-60 chips in the focal plane is used to determine the expected
-astrometry for each chip based on the boresite coordinates and
-position angle reported by the header.  Reference stars are selected
-from the full field of view of the GPC1 camera, padded by an
-additional \note{25\%} to ensure a match can be determined even in the
-presence of substantial errors in the boresite coordinates.  It is
-important to choose an appropriate set of reference stars: if too few
-are selected, the chance of finding a match between the reference and
-observed stars is diminished.  In addition, since stars are loaded in
-brightness order, a selection which is too small is likely to contain
-only stars which are saturated in the GPC1 images.  On the other hand,
-if too many reference stars are chosen, there is a higher chance of a
-false-positive match, especially as many of the reference stars may
-not be detected in the GPC1 image.  The seletion of the reference
-stars includes a limit on the brightest and fainted magnitude of the
-stars selected.
+\section{Astrometric Models} 
 
 Three somewhat distinct astrometric models are employed within the IPP
@@ -278,5 +259,5 @@
 \begin{eqnarray}
   L & = & C^L_{0,0} + C^L_{1,0} X_{\rm chip} + C^L_{0,1} Y_{\rm chip} + \delta L(X_{\rm chip}, Y_{\rm chip}) \\
-  M & = & C^M_{0,0} + C^M_{1,0} X_{\rm chip} + C^M_{0,1} Y_{\rm chip} + \delta M(X_{\rm chip}, Y_{\rm chip}) \\
+  M & = & C^M_{0,0} + C^M_{1,0} X_{\rm chip} + C^M_{0,1} Y_{\rm chip} + \delta M(X_{\rm chip}, Y_{\rm chip}) 
 \end{eqnarray}
 
@@ -289,10 +270,11 @@
   Q & = & \sum_{i,j} C^Q_{i,j} (X_{\rm chip} - X_0)^i (Y_{\rm chip} - Y_0)^j 
 \end{eqnarray}
-
-\note{need to discuss the WCS keywords, both standard and
-  non-standard, used to represent these polynomial transformations}
+\note{need to complete this discussion of the WCS keywords, both
+  standard and non-standard, used to represent these polynomial
+  transformations}
 
 \begin{verbatim}
-CTYPE1,2 : RA---WRP, DEC--WRP & RA---DIS, DEC--DIS (ill-defined since the WRP entries do not generate RA,DEC)
+Here is a table of the keywords and the related terms from Eqns above:
+CTYPE1,2 : RA---WRP, DEC--WRP & RA---DIS, DEC--DIS
 CRVAL1,2 : C^{L,M}_{0,0}
 CRPIX1,2 : X_0, Y_0
@@ -326,4 +308,6 @@
 and photometric data from the reference database.  
 
+\subsection{Reference Catalogs}
+
 During the course of the PS1SC Survey, several reference databases
 have been used.  For the first 20 months of the survey, \code{psastro}
@@ -336,4 +320,23 @@
 catalog.  \note{discuss history of the different refcats?}  
 
+Coordinates and calibrated magnitudes of stars from the reference
+database are loaded by \code{pasastro}.  A model for the positions of
+the 60 chips in the focal plane is used to determine the expected
+astrometry for each chip based on the boresite coordinates and
+position angle reported by the header.  Reference stars are selected
+from the full field of view of the GPC1 camera, padded by an
+additional \note{25\%} to ensure a match can be determined even in the
+presence of substantial errors in the boresite coordinates.  It is
+important to choose an appropriate set of reference stars: if too few
+are selected, the chance of finding a match between the reference and
+observed stars is diminished.  In addition, since stars are loaded in
+brightness order, a selection which is too small is likely to contain
+only stars which are saturated in the GPC1 images.  On the other hand,
+if too many reference stars are chosen, there is a higher chance of a
+false-positive match, especially as many of the reference stars may
+not be detected in the GPC1 image.  The seletion of the reference
+stars includes a limit on the brightest and fainted magnitude of the
+stars selected.
+
 The astrometric analysis is necessarily performed first; after the
 astrometry is determined, an automatic byproduct is a reliable match
@@ -358,8 +361,8 @@
   chip}, Y^{\rm ref}_{\rm chip}$ values for the reference catalog
 stars.  For all possible pairs between the two lists, the values of
-\[
-\Delta X = X^{\rm ref}_{\rm chip} - X^{\rm obs}_{\rm chip}\\
-\Delta Y = Y^{\rm ref}_{\rm chip} - Y^{\rm obs}_{\rm chip}
-\]
+\begin{eqnarray}
+\Delta X & = & X^{\rm ref}_{\rm chip} - X^{\rm obs}_{\rm chip}\\
+\Delta Y & = & Y^{\rm ref}_{\rm chip} - Y^{\rm obs}_{\rm chip}
+\end{eqnarray}
 are generated.  The collection of $\Delta X, \Delta Y$ values are
 collected in a 2D histogram with sampling of \note{XXX} pixels and the
@@ -388,4 +391,7 @@
 astrometry guess for the chip.
 
+\note{option to downweight based on photometric inconsistency : not
+  used in PS1 analysis}
+
 \subsection{Chip Polynomial Fits}
 
@@ -410,6 +416,24 @@
 ($C^{L,M}_{0,0}$) and those which define the offset from focal plane
 to tangent plane ($C^{P,Q}_{0,0}$).  We limit ($C^{P,Q}_{0,0}$) to be
-0,0 to remove this degeneracy.  \note{disucss the measurement of the
-  camera distortion via the gradient}
+0,0 to remove this degeneracy.  
+
+The initial fit of the astrometry for each chip follows the distortion
+introduced by the camera: the apparent plate scale for each chip is
+the combination of the plate scale at the optical axis of the camera,
+modified by the local average distortion.  To isolate the effect of
+distortion, we choose a single common plate scale for the set of chips
+and re-define the chip $\rightarrow$ sky calibrations as a set of chip
+$\rightarrow$ focal plane transformation using that common pixel
+scale.  We can now compare the observed focal plane coordinates,
+derived from the chip coordinates, and the tangent plane coordiantes,
+derived from the projection of the reference coordinates.  One caveat
+is that the chip reference coordinates are also degenerate with the
+fitted distortion.  In order to avoid being sensitive to the exact
+positions of the chips at this stage, we measure the local gradient
+between the focal plane and tangent plane coordinate systems.  We then
+fit the gradient with a polynomial of order 1 less than the polynomial
+desired for the distortion fit.  The coefficients of the gradient fit
+are then used to determine the coefficients for the polynomials
+representing the distortion.  \note{write out the math of the gradients}
 
 Once the common distortion coming from the optics and atmosphere have
@@ -419,16 +443,68 @@
 each iteration, the reference stars and detected objects are matched
 using the current best set of transformations.  These fits start with
-low order (1) and large matching radius (\note{XX}) and reduced the
-radius while allowing the order to increaes, up to 3rd order for the
-final iterations.  \note{quality of the fits as a result of this stage}.
-
-\note{describe the output smf file?}
-
-\note{discuss the real-time photometric calibration}
+low order (1) and large matching radius (\note{XX}).  As the
+iterations proceed, the radius is reduced and the order is allowed to
+increaes, up to 3rd order for the final iterations.  \note{quality of
+  the fits as a result of this stage}.
+
+\subsection{Real-time Photometric Calibration}
+
+After the astrometric calibration has finished, the photometric
+calibration is performed by \code{psastro}.  When the reference stars
+are loaded, the apparent magnitude in the filter of interest is also
+loaded.   Stars for which the reference magnitude is brighter than
+(\grizy) = (19, 19, 18.5, 18.5, 17.5) are used to determine the zero
+points by comparison with the instrumental magnitudes.  For the PV3
+analysis, the robust median \note{defined where?} is used to measure
+the zero point. For early versions of the analysis, when the reference
+catalog used synthetic magnitudes, it was necessary to search for the
+blue edge of the distribution: the synthetic magnitude poorly 
+predicted the magnitudes of stars in the presence of significant
+extinction or for the very red stars, making the blue edge somewhat
+more reliable.  Note that we do not include an airmass correction in
+this zero point analysis: the airmass correction is folded into the
+observed zero point.  The zero point may be measured separately for
+each chip or as a single value for the entire exposure; the latter
+option was used for the PV3 analysis.
+
+\subsection{Real-time outputs}
+
+The calibrations determined by \code{psastro} as saved as part of the
+header information in the output FITS tables.  A single
+multi-extension FITS table is written using the \code{smf} format.  In
+these files, the measurements from each chip are written as a separate
+FITS table.  A second FITS extension for each chip is used to store
+the header information from the original chip image.  The original
+chip header is modified so that the extension corresponds to an image
+with no pixels data: \code{NAXIS} is set to 0, even though
+\code{NAXIS1} and \code{NAXIS2} are retained with the original
+dimensions of the chip.  A pixel-less primary header unit (PHU) is
+generated with a summary of some of the important and common
+chip-level keywords (e.g., \code{DATE-OBS}).  The astrometric
+transformation information for each chip is saved in the corresponding
+header using standard (and some non-standard) WCS keywords.
+\note{combine this discussion with the above?}.  For the two-level
+astrometric model, the PHU header carries the astrometric
+transformation related to the projection and the camera-wide
+distortions.  Photometric calibrations are written as a set of
+keywords to individual chip headers, and if the calibration is
+performed at the exposure-level, to the PHU.  The photometry
+calibration keywords are:
+\begin{itemize}
+\item \code{ZPT_REF} : the nominal zero point for this filter
+\item \code{ZPT_OBS} : the measured zero point for this chip /
+  exposure
+\item \code{ZPT_ERR} : the measured error on \code{ZPT_OBS}
+\item \code{ZPT_NREF} : the number of stars used to measure \code{ZPT_OBS}
+\item \code{ZPT_MIN} : minimum reference magnitude included in analysis
+\item \code{ZPT_MAX} : maximum reference magnitude included in analysis
+\end{itemize}
+The keyword \code{ZPT_OBS} is used to set the initial zero point when
+the data from the exposure are loaded into the DVO database.
 
 \section{DVO Description}
 
 The Pan-STARRS IPP uses an internal database system, distinct from the
-publically visitble database system, to determine the association
+publically visible database system, to determine the association
 between multiple detections of the same astronomical object and as
 part of the astrometric and photometric calibration process.  This
@@ -438,13 +514,4 @@
 this databasing system have been somewhat expanded for the Pan-STARRS
 context.  
-
-DVO includes two major classes of database tables: those containing
-information directly about astronomical objects in the sky and those
-containing other supporting information.  As discussed in detail
-below, the object-related tables are partitioned on the basis of
-position in the sky: objects within a region bounded by lines of
-constant RA,DEC are contained in a specific file.  The boundaries and
-the associated partition names are stored in one of the supporting
-tables.
 
 One of the main purposes of the DVO system is to define the
@@ -460,8 +527,29 @@
 detection is associated with the closest object.  
 
+Detections in DVO have a special piece of metadata called the
+\code{photcode} which identifies the source of the measurement.  A
+\code{photcode} has a name which in general consists of the name of
+the camera or telescope (e.g., GPC1 or 2MASS), the name (or short-hand
+name) of the filter used for the measurement (e.g., $g$), and an
+identifier for the detector, if not unique (e.g., XY01 for GPC1).
+Along with each name, there is a numerical value for the photcode.  A
+table within the DVO system, \code{Photcode}, lists the photcoes and
+defines a number of additional pieces of information for each
+photcode.  These include the nominal zero point and airmass slope, as
+well as color trends to transform a measurement in the specific
+photcode to a common system.  There are 3 classes of photcodes defined
+within the DVO system.  Those photcodes associated with detections
+from an image loaded into the database system are called \code{DEP}
+photcodes.  There are also photcodes associated with the average
+photometry values, called SEC photcodes.  There are also those
+measurements which come from external data sources for which DVO does
+not have any information to determine a calibration (e.g.,
+instrumental magnitudes and detector coordinates).  These are
+measurements are reference values and are assigned REF photcodes.
+
 In the implementation of DVO used for the PV3 calibration analysis,
 the database tables are stored on disk using binary FITS tables.  Each
 type of database table is stored as a separate file, or a collection
-of files if the table is spatially partitioned.  The binary FITS
+of files for table which are spatially partitioned.  The binary FITS
 tables may be optionally compressed using the (to date) experimental
 FITS binary table compression strategy outlined by REF.  In this
@@ -495,4 +583,65 @@
 \code{GZIP_1}, integers use \code{RICE}.  
 
+\subsubsection{Sky Partition}
+
+DVO includes two major classes of database tables: those containing
+information directly about astronomical objects in the sky and those
+containing other supporting information.  The object-related tables
+are partitioned on the basis of position in the sky: objects within a
+region bounded by lines of constant RA,DEC are contained in a specific
+file.  The boundaries and the associated partition names are stored in
+one of the supporting tables, \code{SkyTable}.  This table contains
+the definitions of the boundaries for each sky region (\code{R_MIN},
+\code{R_MAX}, \code{D_MIN}, \code{D_MAX}), the name of the sky region,
+an ID (\code{INDEX}, equal to the sequence number of the region in the
+table), and index entries to enable navigation within the table.  The
+regions are defined in a hierarchical sense, with a series of levels
+each containing a finer mesh of regions covering the sky.  
+
+In the default used by the PV3 DVO, the partitioning scheme is based
+on the one used by the Hubble Space Telescope Guide Star Catalog
+files.  Level 0 is a single region covering the full sky.  Level 1
+divides the sky in Declination into bands 7.5\degree\ high.  Level 2
+subdivides these Declination bands in the RA direction, with spacing
+related to the stellar density.  Level 3 divides these RA chunks into
+4 - 8 smaller partitions.  This level exactly matches the HST GSC
+layout, and uses the same naming convention to identify the
+partitions: n0000/0000, etc. \note{more on the names?}.  Level 4
+further divides these regions by a factor of 16.  In the
+\code{SkyTable}, a region at one level has a pointer to its parent
+region (the one which contains it) and a sequence pointing to its
+children (regions it contains).  The \code{SkyTable} enables fast
+lookups of the on-disk partitions which map to a specific coordinate
+on the sky.  In general, a single DVO will have the full sky
+represented with tables at a single level, though it is possible for
+mixed levels to be used, this mode is not well tested.  For the PV3
+master database, the partitioning at the 5th level results in \approx
+150,000 regions to cover the full sky, of which \approx 110,000 are
+used for the PV3 $3\pi$ data.  The densest portions of the bulge
+contain at most \approx 300k astronomical objects in the database
+files, with an associated maximum of 30M measurements in these files.
+With the compression scheme described above, this makes the largest
+database files \approx 3GB, which can be loaded into memory in 30
+seconds on our partition machines.
+
+The DVO software system allows the tables which are partitioned across
+the sky to also be distributed across multiple computers, which we
+call partition hosts.  A single file defines the names of these
+partition hosts and the location of the database partition on the
+disks of that machine.  The \code{SkyTable} contains elements to
+define by ID the parition host to which a partitioned set of tables
+has been assigned.  Operations which query the database, or perform
+other operations on the database, are aware of the partitioning scheme
+and will launch their operations as remote processes on the machines
+which contain the data they need.  For example, a query for data from
+a small region will launch sub-query operations on the machines which
+contain the data overlapping the region of interest.  These remote
+query operations will select the database information which matches
+the query request (i.e., applying restrictions as defined) and return
+to the master process the results.  The results from the various
+partition hosts are then merged into a single result by the master
+process.  This parallelization is critical to querying and
+manipulating the enormous database on a reasonable timescale.
+
 \subsection{Tables which describe objects} 
 
@@ -607,26 +756,91 @@
 in our analysis of the astrometry (see Section~\ref{sec:astrometry}).
 
-\subsubsection{Sky Partition}
-
-\note{SkyTable}
-
 \subsection{Other Tables} 
 
-\note{Image Table}
-\note{Photcode Table}
-\note{FlatCorrection}
-\note{AstromOffsets}
+Data from GPC1 (and other cameras processed by the IPP) are loaded
+into DVO in units \code{smf} files generated by the Camera calibration
+stage.  As described above, these files contain all measurements from
+a complete exposure, with measurements from each chip grouped into
+separate FITS tables.  When these measurements are loaded into the
+\code{Measure} and similar tables, a subset of the information from
+the chip header is used to populated a row in the DVO \code{Image}
+table.  This table contains one row for each chip known to DVO, with
+information such as the filter (\code{photcode}), the exposure time,
+the airmass, the astrometric calibration terms, the photometric
+zero point, etc.  For GPC1 and other mosaic cameras, an additional row
+is defined to carry the projection and camera distortion elements of
+the astrometry model.  As chips are loaded into this table, they are
+assigned an internal ID (a running sequence in the table).  Images may
+also be assigned an external ID: in the case of the GPC1 images, this
+ID is defined by the processing mysql database and is guaranteed to be
+unique within the processing system. 
+
+Other tables are used to track information used by the calibration
+system.  This includes the complete set of flat-field corrections
+determined by the photometry calibration analysis (see
+Section~\ref{sec:relphot}) and the astrometric flat-field corrections
+determined by the astrometry calibration analysis (see Section~\ref{sec:relastro})
 
 \section{Photometry Calibration}
 
 \subsection{Ubercal Analysis}
-\begin{verbatim}
-* data loaded into LSD database (Juric REF) @ CFA (?).  
-* refer to Ubercal paper
-* modifications for PV3 : 2x2 grid, no new flats
-* result is a collection of zero points for photometric images
-  * discuss stats on the zero points and the airmass terms
-* does eddie still use per exposure or per star airmass terms?
-\end{verbatim}
+
+\note{clean up and re-word the pieces below}
+
+The photometric calibration of the DVO database starts with the
+``ubercal'' analysis technique as described by \cite{PS1.ubercal}.
+This analysis is performed by the group at Harvard, loading data from
+the \code{smf} files into their instance of the Large Scale Database
+(LSD, Juric REF), a system similar to DVO used to manage the
+detections and determine the calibrations.
+
+Photometric nights are selected and all other exposures are ignored.
+Each night \note{shorter time?} is allowed to have a single fitted
+zero point and a single fitted value for the airmass extinction
+coefficient per filter.  The zero points and extinction terms are
+determined as a least squares minimization process using the repeated
+measurements of the same stars from different nights to tie nights
+together.  Flat-field corrections are also determined as part of the
+minimization process.  In the original (PV1) ubercal analysis,
+\cite{PS1.ubercal} determined flat-field corrections for $2\times 2$
+sub-regions of each chip in the camera and four distinct time periods
+(``seasons'').  Later analysis (PV2) used an $8\times8$ grid of
+flat-field corrections to good effect.
+
+The ubercal analysis was re-run for PV3 by the Harvard group.  For the
+PV3 analysis, under the pressure of time to complete the analysis, we
+chose to use only a $2\times 2$ grid per chip as part of the ubercal
+fit and to leave higher frequency structures to the later analysis.  A
+5th flat-field season consisting of nearly the last 2 years of data
+was also included for PV3.  In retrospect, as we show below, the data
+from the latter part of the survey would probably benefit from
+additional flat-field seasons.  \note{something for PV4}.
+
+By excluding non-photometric data and only fitting 2 parameters for
+each night, the Ubercal solution is robust and rigid.  It is not
+subject to unexpected drift or sensitivity of the solution to the
+vagaries of the data set.  The Ubercal analysis is also especially
+aided by the inclusion of multiple Medium Deep field observations
+every night, helping to tie down overall variations of the system
+throughput and acting as internal standard star fields.  The resulting
+photometric system is shown by \cite{PS1.ubercal} to have reliability
+across the survey region at the level of (8.0, 7.0, 9.0, 10.7, 12.4)
+millimags in (\grizy).  As we discuss below, this conclusion is
+reinforced by our external comparison.  \note{do I have a measurement
+  of the bright end stability in PV3?  basically, what is the scatter
+  per star as a function of position in the camera and magnitude?}
+
+The overall zero point for each filter is not naturally determined by
+the Ubercal analysis; an external constraint on the overall
+photometric system is required for each filter.  \cite{PS1.ubercal}
+used photometry of the MD09 Medium Deep field to match the photometry
+measured by \cite{JTphoto} on the reference photometric night of MJD
+55744 (UT 02 July 2011).  \note{Scolnic et al REF} have re-examined
+the photometry of Calspec standards as observed by PS1.  They reject 2
+of the \note{XX} stars used by \cite{JTphoto} and add photometry of
+\note{XX} additional stars.  The calspec spectrophotometry values have
+also been re-examined by XX; using these new measurements, Scolnic et
+al determine new zero points for the PS1 system, which we have applied
+(see below).
 
 \subsection{Applying the Ubercal Zero Points : Setphot}
@@ -898,4 +1112,14 @@
 the bright end.  \note{recommendation}
 
+\subsection{Calculation of Object Photometry}
+
+\subsubsection{Iteratively Reweighted Least Squares Fitting (1D)}
+
+\subsubsection{Seletion of Measurements}
+
+\subsubsection{Stack Photometry}
+
+\subsubsection{Warp Photometry}
+
 \section{PV3 DVO Master Database}
 
@@ -1211,4 +1435,10 @@
 \note{Figures showing the Gaia residuals}
 
+\subsection{Calculation of Object Astrometry}
+
+\subsubsection{Iteratively Reweighted Least Squares Fitting}
+
+\subsubsection{Seletion of Measurements}
+
 \section{Discussion}
 
