PHOTOM- Perform aperture photometry

Description:

PHOTOM performs photometry. It has two basic modes of operation; using an interactive display to specify the positions for the measurements, or obtaining those positions from a file. In both modes the user may perform photometry using either the traditional aperture method or using optimal extraction.

During aperture photometry the aperture can either be circular or elliptical and the size and shape can be varied interactively on the display, or by entering values from the keyboard or parameter system. During optimal extraction the mask clipping radius can also be varied from the keyboard or via the parameter system. The background sky level can be sampled interactively by manual positioning of the aperture, or automatically from an annulus surrounding the object.

PHOTOM is a menu driven application. The menu has been designed around single character entries, which hopefully have easily remembered mnemonics. Many of the options have counterparts in the parameter system, and so can be controlled outside the task by the environment.

Parameters:

ANGLE = _REAL (Read)

The orientation of the ellipse defining the aperture. This is defined in degrees going anti-clockwise from the positive y-axis. This is equivalent to a position angle.

BIASLE = _REAL (Read)

The level in data units per pixel of any constant offset in the image. This should be defined if the errors are to be calculated from photon statistics. If the true value is unknown use a value of 0.

CENTRO = _LOGICAL (Read)

Centre the object before measurement or accept the given position as the centre of the aperture. This is forced to be true for optimal extraction.

If this is TRUE the aperture is centered around the object of interest before the measurement is taken. The position supplied to the program (interactively or from a file of positions) is taken as a starting point and the position of maximum flux is located within a search box of fixed size.

If this is FALSE the position supplied to the program is used as the centre of the aperture.

CLIP = _REAL (Read)

The clipping radius used for the weight mask if optimal photometry is selected. Not to be confused with the mask used to exclude regions from the background estimate (USEMASK parameter)

COMMAND = _CHAR (Read)

The next action. The options are defined by single letter entries and should be one of the following:

A(nnulus) -- This toggles between using an annular background aperture and an interactive aperture.

C(entroid) -- This switches the centroiding of the object in the aperture on and off.

E(xit) -- This command terminates the current PHOTOM session.

F(ile of positions) -- This command takes positions from a file and performs photometry with the current aperture parameters.

H(elp) -- This displays a brief line of help for each command.

I(nteractive shape) -- This allows the size and shape of the aperture to be adjusted interactively on the screen.

M(easure) -- This performs interactive measurements of objects individually selected from the screen.

N(on-interactive shape) -- The size and shape of the aperture (in pixels) is entered from the keyboard.

O(ptions) -- This allows some of the defaulted parameters to be changed from within the program.

P(hoton statistics) -- This selects the method for calculating the errors: either from photon statistics, or from the measured variance in the sky aperture or from the variance component of the data array.

S(ky) -- This selects between the different methods of estimating the background level in the sky aperture.

V(alues) -- This summarizes the current settings of the programs parameters.

(e)X(traction) -- Toggle between doing optimal and aperture photometry.

CONCEN = _LOGICAL (Read)

Find the sky automatically from a concentric aperture or select the sky regions interactively.

If this is TRUE the sky level is estimated from an aperture which is concentric about the object aperture. The shape and orientation of the sky aperture is the same as the object aperture and the size of the annular aperture is defined by the INNER and OUTER parameters. This mode is used if the measurement positions are being supplied from a file. This is the recommended mode for carrying out optimal extraction.

If this is FALSE the sky level is estimated from an aperture equal in size and shape to the object aperture, which is positioned manually on the image display. In this mode several consecutive sky measurements can be made around the object of interest and these are averaged to give the final sky estimate.

DEVICE = DEVICE (Read)

The name of the device to be used for interactive measurements on which the data has been displayed. If the device has an overlay plane then this should be selected.

ECCEN = _REAL (Read)

The eccentricity of the ellipse defining the aperture. For a circular aperture this should be set to 0.0.

EXSOURCE = LITERAL (Read)

The ``source'' of the image exposure time supplied via the ETIME parameter. This can take one of the values, HDS, CONSTANT or HEADER, with the following meanings:

HDS: indicates that the exposure value is stored in an HDS object somewhere in the image (this presumes that the image is an NDF and corresponds to the original behaviour of PHOTOM, prior to the introduction of this parameter).

CONSTANT: indicates that a simple floating point value will be supplied for the image exposure time.

HEADER: indicates that the value to be used is stored in the image header (i.e. FITS headers).

[HDS]

ETIME = LITERAL (Read)

A string that, according to the value returned for parameter EXSOURCE, allows the exposure time of the image to be determined. If EXSOURCE is defined as:

HDS:

then a fully qualified HDS path to the required object within the NDF should be given. For instance if the exposure time is stored in the CCDPACK extension of an NDF, under the item ETIME then a suitable return would be:

more.ccdpack.etime

The HDS structure of an NDF can be viewed using the HDSTRACE utility (see SUN/102).

CONSTANT:

then a floating point value should be given.

HEADER:

then the name of the associated item should be given (e.g. the FITS item EXPOSURE).

[!]

IN = IMAGE (Read)

Name of the image on which the photometry will be performed.

INNER = _REAL (Read)

The radius of the inner edge of the annular sky aperture in units of the object aperture size. The actual dimension in pixels is obtained by multiplying this factor by the object aperture semi-major axis in pixels.

MASKFILE = FILENAME (Read)

Name of the file containing the positions to be used as centers for masking objects from the sky aperture. The file should contain a minimum of three columns the first of which contains an integer index number and the next two contain an x and y position.

MASKRAD = _REAL (Read)

The radius in pixels of the circles used to mask out objects from the background estimate. A pixel which is inside the sky aperture and inside a masked region is not included in the background estimate.

MAXITER = _INTEGER (Read)

The maximum number of iteration steps to be used in locating the object centroid.

MAXSHIFT = _REAL (Read)

The maximum allowable shift in pixels between the initial object position and the calculated centroid.

OPTIMA = _LOGICAL (Read)

If this is TRUE then optimal rather than aperture extraction is used for photometric measurement. The default, for backward compatibility reasons, is FALSE.

OUTER = _REAL (Read)

The radius of the outer edge of the annular sky aperture in units of the object aperture size. The actual dimension in pixels is obtained by multiplying this factor by the object aperture semi-major axis in pixels.

PADU = _REAL (Read)

The number of photons for each interval of the data. If the true value is unknown use a value of 1, in which case the quoted measurement errors will be wrong by the unknown factor SQRT(PADU).

PHOTON = _INTEGER (Read)

Select the method for calculating the measurement errors. There are three possible choices selected by the integers 1 to 4 which have the following bindings:

1. The errors are estimated from the photon statistics in the sky and object apertures. The parameters PADU and BIASLE should be set to their appropriate values to convert the data units to photon numbers.
2. The errors are estimated from the measured variance in the sky aperture. This method assumes that the measured variance is due to photon statistics and estimates the error in the object aperture accordingly. The PADU parameter should be set to its appropriate value to convert the data units to photon numbers.
3. The errors are estimated from the variance component of the data array.
4. The errors are estimated from the measured variance in the sky aperture. This method assumes that the errors are Gaussian (same value per object and sky pixel), and thus requires no knowledge of the values of PADU and BIASLE, but can only be considered an upper limit on the error in a measurement.

POSFILE = FILENAME (Read)

Name of the file containing a list of positions for measurement. The file should contain a minimum of three columns the first of which contains an integer index number and the next two contain an x and y position.

POSITIVE = _LOGICAL (Read)

Find the object centroid for image features which are positive or negative with respect to the background. This should be set to TRUE.

RESFILE = FILENAME (Write)

Name of the file to receive the results of the measurements.

SATURE = _REAL (Read)

The saturation level in data units for the image. If any pixels in the object aperture have values greater than this then the measurement is flagged with an `S' in the output record.

SEARCH = _INTEGER (Read)

The size of the search box in pixels to be used in locating the object centroid.

SEE = _REAL (Read)

Approximate seeing in pixels, used to estimate the FWHM of the point spread function (PSF) by the optimal extraction algorithm.

SEMIM = _REAL (Read)

The semi-major axis of the ellipse defining the aperture in pixel units. For a circular aperture this corresponds to the radius in pixel units.

SKY = _REAL (Read)

A constant value to be used as the sky estimate for subsequent measurements. This defines the sky level in data units per pixel. This value is used until another estimator is chosen.

SKYEST = _INTEGER (Read)

Select the estimator to be used to evaluate the background level in the sky aperture. There are four possible choices selected by the integers 1 to 4 which have the following bindings:

1. Mean. All pixels in the sky aperture are averaged.
2. Mean with 2 sigma rejection. All pixels with data values within 2 standard deviations of the mean are averaged.
3. Mode. The peak of the histogram of pixel values (the most likely value) in the sky aperture is estimated. This is the recommended choice when using optimal extraction.
4. A constant. A single value to be used for all measurements. A sky variance (standard deviation) is also requested so that a realistic error can be assigned to the measurements if the error is calculated from the variance in the sky aperture.

SKYMAG = _REAL (Read)

The magnitude assigned to the sky level when calculating the magnitude of the object using the relation OBJMAG = SKYMAG - 2.5 $*$ LOG10( SIGNAL ) where SIGNAL is the brightness of the object minus sky in photons.

SKYSIG = _REAL (Read)

A constant value for the sky variance. This is an estimate of the standard deviation in the sky level in data units and is used when SKYEST is 4.

TOLER = _REAL (Read)

The required positional accuracy in pixels to terminate the centroiding iterations.

USEMAGS = _LOGICAL (Read)

If TRUE then the output values are converted into magnitudes. If FALSE the output values MAG and MAGERR are modified to be a mean photon count and the error in this count, the other values remain the same, i.e. the sum of sky corrected photons and the mean sky value. Note the SKYMAG value is not used when this is FALSE. Note also that this value may only be set once when PHOTOM is started and must be set either on the command line (USEMAGS=TRUE or USEMAGS=FALSE) or in response to a forced prompt (command line argument PROMPT). [TRUE]

USEMASK = _LOGICAL (Read)

Define a mask to exclude regions from the background estimate. If this is TRUE a file of positions is requested which define the centres of circles used to block regions from the sky aperture. Contaminating objects, such as bright stars, can thus be removed from the background estimate.

Examples:

PHOTOM ARP199

Performs aperture photometry on image ARP199.

PHOTOM SEARCH=5 MAXSHIFT=2.0

Defines the centroiding search box to be 5 pixels wide and the maximum shift of the centroid from its initial, rough position to be 2 pixels.

PHOTOM EXSOURCE=HDS ETIME=MORE.EXP_TIME

An exposure time for the frame will be found in the primitive component EXP_TIME which is a component of the structure MORE in the data file.

PHOTOM USEMASK=T

A mask file will be used to define regions to be excluded from the sky aperture.

PHOTOM USEMAGS=FALSE

This will output the photometry results in photon counts, so the MAG field will now have a mean photon count and MAGERR the error in this count (assuming poissonian statistics are valid).

Aperture Extraction - Format of Associated Files:

At present the file containing the positions of objects to be measured, given by the POSFILE parameter (command F), is read in in free format. The first three columns of the input file have to contain an index number (INTEGER), and the x and y positions (REAL) in that order. The index number is passed to the output to assist in identification of the objects.

The output on the screen contains column headers to indicate the content of each column of the results. These column headers do not appear in the output file given by the RESFILE parameter in order that this file can be accessed by database routines.

There are eleven columns in the output file containing the following information :

   Column 		 Name 		 Description 


1 		 INDEX 		 Index number of star.


2 		 XPOS 		 X position of centre of aperture in pixels.


3 		 YPOS 		 Y position of centre of aperture in pixels.


4 		 MAG 		 Magnitude or mean photon count of star.


5 		 MAGERR 		 Error in MAG.


6 		 SKY 		 Sky value in photons per pixel.


7 		 SIGNAL 		 Total number of photons in aperture due to star.


8 		 CODE 		 Error code flag.


9 		 SEMIM 		 Semi-major axis of aperture.


10 		 ECCEN 		 Eccentricity of aperture.


11 		 ANGLE 		 Orientation of aperture in degrees.

The magnitude (MAG) is calculated from $mag = SKYMAG - 2.5 \log_{10}(signal)$.

The error in the magnitude (MAGERR) is estimated using one of the methods expounded in appendix (note this error is not transformed into magnitudes when USEMAGS is FALSE).

The error CODE can take on three possible values

   B 		 One or more pixels in the object aperture is bad.


S 		 One or more pixels in the object aperture is above the saturation level.


E 		 The object aperture intersects the edge of the data array.

? 		 There are other problems with the measurement.   

If a bad pixel occurs in the object aperture then the pixel is not included in the calculation of the object signal. The bad pixel is not replaced by an estimate. If a saturated pixel occurs in the object aperture then it is included in the calculation of the object signal. If the aperture intersects the edge of the data array, the object signal is calculated for the reduced area of the aperture.

Only one of these code letters is displayed, even if more than one of the conditions has occurred. The codes are in a increasing hierarchy 'B', 'S', 'E', such that 'S' overrides 'B', and 'E' overrides 'S'.

Optimal Extraction - Format of Associated Files:

As for aperture extraction the file containing the position of objects to be measured (command F) is read in free format as above. However in the case of optimal extraction the first line of the file must have an index number (INTEGER) of 0 along with the x and y position of the PSF candidate star.

The output on the screen contains column headers to indicate the content of each column of the results. These column headers do not appear in the output file given by the RESFILE parameter in order that this file can be accessed by database routines.

The first line of the output file will contain the details of the PSF star, there will be seven columns in this line containing the following information :

   Column 		 Name 		 Description 


1 		 INDEX 		 Index number of star.


2 		 XPOS 		 X position of centre of aperture in pixels.


3 		 YPOS 		 Y position of centre of aperture in pixels.


4 		 FWHM1 		 1st FWHM of the point spread function.


5 		 FWHM2 		 2nd FWHM of the point spread function.


6 		 ROT 		 Rotation from perpendicular.


7 		 CODE 		 Error code flag.

The remaining lines contain details of the measurements, each of these lines will have eight columns with the following information :

   Column 		 Name 		 Description 


1 		 INDEX 		 Index number of star.


2 		 XPOS 		 X position of centre of aperture in pixels.


3 		 YPOS 		 Y position of centre of aperture in pixels.


4 		 MAG 		 Magnitude or mean photon count of star.


5 		 MAGERR 		 Error in MAG.


6 		 SKY 		 Sky value in photons per pixel.


7 		 SIGNAL 		 Total number of photons in aperture due to star.


8 		 CODE 		 Error code flag.