AUTOPHOTOM- Do aperture photometry on a list of objects

Description:

This program performs photometry of a list of objects. It is designed to be used non-interactively (i.e. by the GAIA - SUN/214- photometry tool or script). It provides more flexibility than the automated mode of the PHOTOM program by allowing the specification of sky regions other than in annular regions. The results of the measurements are recorded in another file which has the same format as the input file (and can therefore be passed back to this routine and the same measurements can be repeated on a new frame). The format of this file is different for aperture and optimal extraction and is described in the relevant sections.

Usage:

AUTOPHOTOM IN INFILE OUTFILE

Parameters:

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 then return 0.

CENTRO = _LOGICAL (Read)

Centre the object before measurement or accept the given position as the centre of the aperture. This parameter 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 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)

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).

[!]

FIXANN = _LOGICAL (Read)

If TRUE then any annular regions in the input description file are interpreted as radii (in pixels) along the aperture major axis, otherwise they are interpreted as scale factors of the major axis. [FALSE]

INFILE = LITERAL (Read)

Name of the file containing the descriptions of the objects to measure and the positions and nature of any sky regions associated with them. See the notes section for the format of this file.

IN = IMAGE (Read)

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

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. [TRUE]

MASK = LITERAL (Read)

An ARD description of any regions to be excluded from the image before any calculations of sky and object are performed. The ARD language is described in SUN/183. A filename can be given using the indirection character ``$\wedge$''

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.

OUTFILE = FILENAME (Read)

Name of the file to contain the updated descriptions of the measured objects. See the notes section for the format of this file.

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.

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.

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.

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.
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.

Not used if USEMAGS is FALSE.

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.

USEMASK = _LOGICAL (Read)

Define a mask to exclude regions from the background estimate. If this is TRUE an ARD description is requested. Contaminating objects, such as bright stars, can thus be removed from the background estimate.

Notes:

• Aperture Extraction - The input/output file must contain one line per-object that has the following information:

  INDEX XPOS YPOS MAG MAGERR SKY SIGNAL CODE MAJOR ECCEN ANGLE POSITIONS SHAPE

  Where the fields have the following meaning:
  

  INDEX	=	unique integer identifying this object.
  XPOS	=	X coordinate of object.
  YPOS	=	Y coordinate of object.
  MAG	=	current magnitude/mean count of object.
  MAGERR	=	current error in magnitude/mean of object.
  SKY	=	current estimate of sky value for object.
  SIGNAL	=	current estimate of the total count in object.
  CODE	=	current object status.
  MAJOR	=	length of semimajor axis of aperture.
  ECCEN	=	eccentricity of object aperture.
  ANGLE	=	position angle of object aperture.
  POSITIONS	=	how the sky regions are determined.
  SHAPE	=	shape of the aperture.

  
  Values that are unknown initially (MAG, MAGERR, SKY, and SIGNAL) should be set to 0.0, the derived values will be used to replace these fields on exit. The CODE field should be set to ``OK'' initially. The POSITIONS field should have one the values ``annulus'' or ``regions'', to indicate how the sky regions are determined (this is ignored if SKYEST is 4). The SHAPE field should be set to ``circle'' or ``ellipse'' to indicate the aperture shape.
  

  Other lines in the file may be comments or definitions of the sky regions. Comment lines start with the ``#'' character, sky regions either with ``#ANN'' or ``#SKY'' (the # is used so that other programs can skip over this information). If the POSITIONS field of an object is set to ``annulus'', then at least one ``#ANN'' line must be present for this object, this defines the scales or sizes for the inner and outer loci of the sky region.

  #ANN INDEX INNER_SCALE|SEMI_MAJOR OUTER_SCALE|SEMI_MAJOR

  The INDEX value is the identifier of the related object. If POSITIONS is set to ``regions'' then as many lines starting with ``#SKY'' should be present as there are regions (circular or elliptical apertures) in which to estimate the sky value for this object.

  #SKYn INDEX XPOS YPOS SHAPE MAJOR ECCEN ANGLE

  The ``n'' added to the ``#SKY'' identifier indicates the number of the sky region being defined and is optional. The other fields are the same as for an object aperture.
  

• Optimal Extraction - Then the first star in the file must be the PSF. In this case the following information must be provided:

  INDEX XPOS YPOS FWHM1 FWHM2 ROT CODE CLIP SEE POSITIONS

  Where the fields have the following meaning:
  

  INDEX	=	For PSF star this MUST be 0.
  XPOS	=	X coordinate of object.
  YPOS	=	Y coordinate of object.
  FWHM1	=	FWHM of the PSF in the X-direction.
  FWHM2	=	FWHM of the PSF in the Y-direction.
  ROT	=	Rotation of the FWHM from strict X-Y orientation.
  CODE	=	current object status.
  CLIP	=	clipping radius
  SEE	=	estimate of the seeing in pixels
  POSITIONS	=	how the sky regions are determined.

  
  Values that are unknown initially (eg FWHM1, FWHM2, ROT) should be set to 0.0, the derived values will be used to replace these fields on exit. The CODE field should be set to ``OK'' initially. The POSITIONS field should have one the values ``annulus'' or ``regions'', to indicate how the sky regions are determined (this is ignored if SKYEST is 4). Aperture must be circular for optimal extraction so no SHAPE field is provided.
  

  Further stars should be entered with the following information:

  INDEX XPOS YPOS MAG MAGERR SKY SIGNAL CODE POSITIONS

  Where the fields have the following meaning:
  

  INDEX	=	unique integer identifying this object.
  XPOS	=	X coordinate of object.
  YPOS	=	Y coordinate of object.
  MAG	=	current magnitude/mean count of object.
  MAGERR	=	current error in magnitude/mean of object.
  SKY	=	current estimate of sky value for object.
  SIGNAL	=	current estimate of the total count in object.
  CODE	=	current object status.
  POSITIONS	=	how the sky regions are determined.

  
  Values that are unknown initially (MAG, MAGERR, SKY, and SIGNAL) should be set to 0.0, the derived values will be used to replace these fields on exit. The CODE field should be set to ``OK'' initially. The POSITIONS field should have one the values ``annulus'' or ``regions'', to indicate how the sky regions are determined (this is ignored if SKYEST is 4).
  

  Note that the same clipping radius will be used for all stars (this is an entirely proper and necessary restriction under the algorithm).
  

  Other lines in the file may be comments or definitions of the sky regions. Comment lines start with the ``#'' character, sky regions either with ``#ANN'' or ``#SKY'' (the ``#'' is used so that other programs can skip over this information). If the POSITIONS field of an object is set to ``annulus'', then at least one ``#ANN'' line must be present for this object, this defines the scales or sizes for the inner and outer loci of the sky region.

  #ANN INDEX INNER_SCALE|SEMI_MAJOR OUTER_SCALE|SEMI_MAJOR

  The INDEX value is the identifier of the related object. A good estimate of the inner radius of the sky box is about twice the FWHM of the PSF star
  

  If POSITIONS is set to ``regions'' then as many lines starting with ``#SKY'' should be present as there are regions (circular or elliptical apertures) in which to estimate the sky value for this object.

  #SKYn INDEX XPOS YPOS SHAPE MAJOR ECCEN ANGLE

  The ``n'' added to the ``#SKY'' identifier indicates the number of the sky region being defined and is optional. The other fields are the same as for an object aperture.
  

  It is VERY heavily recommended that annuli are used for sky measurement when using the optimal extraction algorithm unless there are obvious reasons for not doing so.

Pitfalls

• The format of the object file must be correct.