Enclosed Count Fractions
------------------------

These data parameterize the Chandra PSF using ellipses.  The ellipse
parameters are a function of energy, off-axis angle, azimuth, and
enclosed count fraction (ECF).  The ECF is simply the fraction of the
total number of counts contained within a given ellipse.  The ECF
is measured in a plane perpendicular to the telescope's optical axis.

Ellipse fitting algorithm
-------------------------

We have developed the following algorithm to derive ellipses which contain
given fractions of the total counts.  There are undoubtedly others;
this one is relatively stable in the presence of the underlying
structure in the PSF at large off-axis angles.

The ellipses are generated from simulations of the PSF using SAOsac. 

  * A moment-analysis technique is used to fit an initial set of
    ellipses to the raytrace data.

    - An initial ellipse is generated by calculating the moments of the 
      99% of the rays closest to the sigma-clipped center of the
      rays.

    - Additional ellipses are generated by calculating the moments of
      the subset of rays that lie within a circle with radius 80%
      of the semi-major-axis of the previous, containing ellipse. This
      process is repeated until a useful number of ellipses is
      generated, or the ellipses grow small enough that the process
      stalls.

  * This set of ellipses is used to interpolate a final set of
    ellipses at specific values of the ECF.

This process was repeated for 100 different realizations of each set
of input parameters (off-axis angle, azimuth, and energy) to derive
the variation due to random sampling of the model.  The median and
the 15.87 and 84.13 percentiles (which enclose the inner 68.26% of the
values, corresponding to Gaussian 1 sigma deviations) are extracted
for each set of realizations.


See the SPIE memo: 

    "A Parameterization of the Chandra Point Spread Function"
    X-Ray Instruments and Missions, SPIE Meeting Volume 5165, 
    Christopher L. Allen et al, August 2003
    ISBN# 0-8194-5038-3

    http://cxc.harvard.edu/cal/spie/parameterized_psf.ps

for an in-depth description of the ECF generation process.


File Format
-----------

The FITS file structure follows the general directions of the OGIP
Calibration Memo CAL/GEN/92-020 for radial encircled energy functions
(REEF). That document has several inconsistencies which prevent
following it to the letter.

Here's a practical summary of the format used here.  The FITS file
contains a binary table HDU, consisting of a single row.  Each column
in the row is a vector.  The columns ECF, THETA, PHI, ENERGY,
ENERG_LO, and ENERG_HI contain 1D vectors.  The columns X_CTR, Y_CTR,
SMA, SMB and PA  contain 4D matrices.  The matrix shape is
given by the TDIMm parameters. The order in which the coordinates
vary, from most frequently to least frequently, is given by the
nCTYPEm keywords (summarized in CREFm).

The input parameters are specified in the 1D vectors. To determine the
ranges of input parameters, simply display the contents of the ECF,
THETA, PHI, and ENERGY columns.

 dmlist hrmaD1996-12-20hrci_ell_ecf_N0003.fits'[cols theta,phi,energy,ecf]' \
        opt=array

The contents of the columns are as follows:

ECF:	The enclosed count fraction; the fraction of the total counts
        in the ellipse.
	

ENERG_LO, ENERG_HI:
	The energy range in keV for which the ellipses are valid.

ENERGY:
	The midpoint of the valid energy range, in keV.

THETA:	The off-axis angle of the source in minutes of arc.

PHI:	The azimuthal angle of the source in degrees (oriented in
	Mirror Spherical Coordinates)

Y_CTR, Z_CTR:
	The centers of the ellipses in telescope coordinates.  The
	centers are relative to the initial sigma-clipped centroid of
	the raytrace.  They are in units of seconds of arc.

SMA, SMB:
	The semi-major and semi-minor axes of the ellipses, in seconds
	of arc.

PA:	The position angle of the ellipse, in degrees measured from
	the positive Y axis, increasing towards the positive Z axis. 


The columns Y_CTR, Z_CTR, SMA, SMB, and PA are the median of the 100
realizations for the values of ECF, THETA, PHI, and ENERGY.  Each of
these columns has two accompanying columns (same name, but with
suffices of _SMIN and _SMAX) which contain the values bounding the
central 68.26% of the realizations.  These indicate the variation of
the ellipse parameters due to randomly sampling the model. No
systematic errors are yet included.


Usage
-----

The parameterization is given as

    PARAM(ECF,THETA,PHI,ENERGY)

where PARAM is one of Y_CTR, Z_CTR, SMA, SMB, or PA

How to use this mess?  Look up your favorite values in the ECF, THETA,
PHI, ENERG_LO/ENERG_HI vectors and save their indices into those
vectors.  Use those indices to calculate an offset into the RADIUS
matrix.  

C:

If you read the 4D matrices directly in C, the matrix looks
like this:

        PARAM[iENERGY][iPHI][iTHETA][iECF]

Or, dealing with pointers:

        param + iECF 
              + iTHETA  * ( nECF )
              + iPHI    * ( nECF * nTHETA ) 
              + iENERGY * ( nECF * nTHETA * nPHI )

Fortran:

        PARAM(iECF,iTHETA,iPHI,iENERGY)


PDL:

After reading in the data, reshape it:

   param->reshape( $ecf->nelem, $theta->nelem, $phi->nelem, $energy->nelem);

and read it in:

    param($iECF, $iTHETA, $iPHI, $iENERGY);     # using NiceSlice
    param->at($iECF, $iTHETA, $iPHI, $iENERGY); # standard PDL