5 Performing interactive analyses

 5.1 The PHOTOM menu options
 5.2 Defaulted parameters

Interactive measurement is performed in PHOTOM using a program which is also called PHOTOM1. Alternatively, if it is available on your system, you can use the photometry toolbox which is part of the GAIA (SUN/214) display tool. In the following discussion it is assumed that you are using the PHOTOM program.

The first thing you need to do is display your image. Although PHOTOM can work using a display that does not have an overlay, it is best to have one. This is so that any line graphics which PHOTOM draws can be erased. Without this ability the display becomes quickly confused, particularly when setting the size and orientation of the aperture.

You can create a GWM X-windows display with an overlay using the command:

  % xmake xwindows -overlay -ovcolour green

and can display an image in this window either using the KAPPA (SUN/95) DISPLAY program, or if this isn’t available the PHOTGREY program.

You can now start up the main PHOTOM program by typing the command:

  % photom

this could be from the C-shell or ICL.

The first response from this program is a request for the name of the image you have just displayed. This image remains open until you exit from PHOTOM. If you need to measure objects in another image then you should exit PHOTOM, display the new image and then restart PHOTOM.

The next request should be for a parameter “COMMAND” which indicates that you are now in the main command loop of PHOTOM. Your response to this prompt should be a single character. To see a menu of the possible commands return a ‘h’ (or ‘H’).

The first time one of the interactive graphical options: I – interactive shape (aperture photometry only); or M – interactive measurement is selected the name of the display device is requested. If you are using an image display with overlay capabilities then remember that the overlay device is not the same as the device you displayed your image in, e.g. if you displayed on an X-windows device ‘xw’, then the overlay device is called ‘xov’.

Typically the cursor position is controlled by the mouse and the mouse button meanings are indicated by three menu boxes drawn on the screen. If you use an unusual display device without a mouse then the graphics are controlled by the keyboard. A message from PHOTOM shows which of these options applies to you.

5.1 The PHOTOM menu options

The following section describes each of the menu items that you can use at the COMMAND prompt.

5.1.1 A — annulus

This is a toggle switch which alters the way in which the background level is measured. There are two methods available. The first is interactive, and uses an aperture identical in size and shape to the object aperture. The aperture is positioned manually to select the region of sky to measure. The message ‘Interactive aperture in use’ will signify that this has been chosen.

When using the interactive aperture, several sky areas can be sampled to improve the estimate of the sky. The sky estimates from each aperture are simply summed, and the mean of these is used when the object is measured.

The alternative is to use an aperture which is a concentric annulus around the object aperture. In this mode the sky is measured automatically every time a measurement is made. The message ‘Concentric aperture in use’ signifies this choice. The size of the sky aperture is specified by the INNER and OUTER parameters. These are defined as multiplying factors of the object aperture size, or in optimal extraction mode of the clipping radius, e.g. if INNER were 2 and OUTER 3 then the sky aperture would start at two radii from the centre and end at three radii.

When starting PHOTOM one of these modes will be chosen as the default. This choice is controlled by the CONCEN parameter. If the positions of the objects is entered by a file of positions (command F), then the background is automatically taken with the concentric annulus, whatever the default value of CONCEN.

5.1.2 C — centroid

This is a toggle switch which alters whether the object is centered in the aperture before doing the measurement. Centroiding is controlled by the parameters SEARCH, POSITIVE, MAXSHIFT, MAXITER and TOLER. These cannot be changed from within the program, and if alternative values are required they should be given on the command-line when starting PHOTOM. For instance:

  % photom positive=f

would make PHOTOM centroid on objects whose signal was negative (not a very likely choice).

The choice of mode is indicated by the messages ‘Centroiding in stellar aperture’, or ‘No centroiding’. When starting PHOTOM one of these modes will be chosen as the default. Centroiding cannot be turned off when using optimal extraction.

Unless the field under investigation is very crowded, or there are other special conditions, it is probably best to leave the centroiding option on all the time. This is more important if the measurements are being made in non-interactive mode (command F); unless you’re certain that the positions are accurate for all images.

5.1.3 E — exit

This command exits PHOTOM.

5.1.4 F — file of positions

This command causes the measurements to be done automatically. A file containing the positions is requested, and the photometry is performed with the current parameters.

The name of the file containing the positions is requested through the POSFILE parameter. If the file cannot be found or is not in a suitable format then no action is taken.

The file of positions is an ordinary text file and should specify an index number and the x and y positions in pixel coordinates. For every x and y pair in the file an measurement is made, sampling the sky with the concentric annulus, whose size is specified by the current values of the INNER and OUTER parameters. Centroiding in the object aperture is, or is not done, depending on the current value of the CENTRO parameter, which is selected with command C. When the input file is exhausted PHOTOM returns to the command level.

If optimal extraction is enabled the first entry in the the POSFILE should have index 0 and x and y co-ordinates corresponding to the chosen PSF star.

Results of the measurements are shown on the terminal as well as output to the file named by the RESFILE parameter. Results are identified by the index number associated with the x and y position in the input file.

A previous results file can be used as the input file of positions, but it should not have the same name as the results file otherwise the program will fail when it tries to open a new results file.

The format of the input and the results files are given with the full PHOTOM description in appendix 0.

5.1.5 H — help

This displays a brief line of help for each command. For more extensive information refer to this manual or the on-line help.

5.1.6 I — interactive shape

This allows the size and shape of the aperture to be adjusted interactively on the screen to best suit the objects. When using optimal extraction this command is disabled, the clipping radius can be changed using the O menu option.

The size and shape of the aperture is governed by the three ellipse parameters, the semi-major axis (in pixels), eccentricity and position angle. The semi-major axis and eccentricity are as usually defined for an ellipse. An eccentricity of 0 gives a circular aperture with a radius equal to the semi-major axis. The orientation of the ellipse is given in degrees and specifies the orientation of the semi-major axis of the ellipse anti-clockwise with respect to the vertical axis of the screen.

When this option is chosen five boxes appear on the graphics display. The upper two show the parameter that will be changed and its current value. The lower three boxes show the functions that are performed by the mouse buttons (or keys if your device doesn’t support a mouse). Mouse button 1 (or key 1) changes the parameter to one of SEMI-MAJOR, ECCENTRICITY or ORIENTATION. Mouse button 2 (or key 2) changes the value of the parameter and finally mouse button 3 (or key 0) completes defining the aperture shape and returns you to the COMMAND prompt.

The parameters only have a limited number of preset values which can be cycled through by repeated presses of the middle mouse button (key 2). If the range or interval of the values associated with a parameter aren’t suitable then you can override these by setting a specific value using the N menu option.

When a parameter value is changed, the aperture displayed at the cursor position is updated to reflect this. The aperture is also redisplayed whenever the first mouse button is pressed (or key 1). As this only changes the current parameter rather than any of the actual values, you can use this function to reposition the aperture to inspect its suitability on more than one object (but remember to return to the aperture parameter that you want to change before attempting to alter a value).

The initial values of the three parameters are just the current ones. The semi-major axis can be changed from a maximum of double to a minimum of a half of the current value (with steps of a tenth or fifth of this interval). The possible values of the eccentricity and orientation are limited, to a number of preset values. The value initially displayed is taken to be the member of the preset table which is closest to, but lower than, the current value of that parameter.

5.1.7 M — measure

This performs interactive measurements of objects individually selected from the displayed frame. If using aperture extraction the size and shape of the cursor should be set-up in advance using the I or N commands, while the clipping radius should be set (using the 0 command) when using optimal extraction.

There are two basic methods for measurement of background. Either the background is sampled from an annulus around the object aperture, or from a separately chosen area of sky (see command A). The two cases can be distinguished at this stage from the on-screen display.

In the case of the manual sky measurement the middle box is labelled with SKY, while for automatic sky measurement it will remain empty. The left-hand box with either be labelled STAR, in the case of aperture extraction, or PSF when optimal extraction is selected. The remaining right-hand box will be annotated RETURN TO KEYBOARD.

To perform the measurements with the automatic sampling of the sky, the cursor is positioned over the chosen object and the left-hand mouse button (or key 1) is pressed. If optimal extraction is selected the first measurement will define the point spread function (PSF) for the technique. It is important to pick a bright star which is unsaturated for this task. After this measurement has been taken, if you are using a terminal capable of erasable line graphics such as an xoverlay, then the left-hand box label will change to read STAR to denote that further measurements will be photometric.

For further measurements using optimal extraction, or all measurements using the older aperture method an aperture is displayed where the measurement was made. For optimal extraction this “aperture” will be the size of the clipping radius (the CLIP parameter). If centroiding is being done (command C), automatic enabled for optimal extraction, then the displayed aperture may not be centered on the cursor position. The results of the measurement are printed on the terminal and recorded in the results file. Measurements can be continued until the third mouse button (key 0) is pressed.

When using manual selection of the background the middle mouse button (key 2) is also used. Selecting this button records the sky estimate in an aperture identical in size and shape to the object aperture, at the position specified by the cursor. On the screen an aperture is displayed at that position. No centroiding is done in this aperture, even if the centroiding option is on. When the measurement of the object is made, the most recent value of the sky is used. This means that the sky has to be sampled BEFORE the measurement of the object. Having a correct background estimate is crucial for optimal extraction to such an extent that PHOTOM will not allow you to make a star or PSF measurement using this method until a background measurement has been provided. If the background needs to be sampled in several places around an object, to minimise the noise or take account of a sloping background, then a sky aperture can be selected a number of times and the mean of these values is used. The calculation of the mean is only cleared when an object is measured, so if a mistake has been made in estimating the mean of the skies then an object measurement has to be made, and a note made that the measurement was in error, before going back to the estimation of the sky. Control stays with the interactive menu until the third mouse button (key 0) is pressed.

The results of the measurements are displayed on the terminal and sent to the file accessed by the RESFILE parameter.

5.1.8 N — non-interactive shape

The size and shape of the aperture can be specified from the keyboard by entering values for the semi-major axis (in pixels), the eccentricity and the orientation of the ellipse defining the aperture. When using optimal extraction this command is disabled, the clipping radius can be changed using the V menu option.

An eccentricity of 0 gives a circular aperture with a radius equal to the semi-major axis. The orientation of the ellipse is given in degrees and specifies the rotation of the semi-major axis of the ellipse anti-clockwise with respect to the vertical axis of the pixel array.

5.1.9 O — options

This allows changes of the values of some of the non-aperture shape related parameters.

The INNER and OUTER parameters define the size of the annulus to be used in the automatic sampling of the sky. The annulus has the same elliptical shape as the object aperture, but is larger by the factors given by INNER and OUTER. These two parameters are given in terms of multiplicative factors of the semi-major axis of the object aperture. Thus an INNER radius of 1 means that the sky annulus starts where the object aperture ends. The annulus thus grows and shrinks with changes to the object aperture.

The PADU parameter defines the number of photons for each interval of the data. Multiplying the data value in each pixel by PADU gives the number of photons recorded (after correcting for BIASLE). If this parameter is unknown then leave it at 1. It is necessary to provide an estimate of this number if optimal extraction is to be carried out correctly.

The SKYMAG parameter specifies the magnitude to be given to the sky when calculating the magnitude of the object. The magnitude of the object is calculated from mag = SKYMAG 2.5 log 10(signal) where signal is the brightness of the object minus sky in photons. This parameter is not used if USEMAGS is set to FALSE (in this case the output is not in magnitudes).

The BIASLE parameter gives the level in data units of any offset in the bias level per pixel. This is needed if there is any non-photon source of background, and proper photon statistics are required. If this parameter is unknown then leave it at 0.

The SATURE parameter is the saturation level for the image in data units. If there are any pixels in the object aperture with values greater than the saturation level then this is indicated by an error code ’S’ in the final column of the output table. The object magnitude is calculated with the saturated pixel included in the result. So changing the value of this parameter will not change the results but will alter the number of objects flagged in the output file.

The CLIP parameter is clipping radius of the weight mask used in optimal extraction. This is needed if optimal extraction is enabled and defaults to 5 pixels. If optimal extraction is not enabled (using the X command) then the CLIP parameter will not appear in the list when the options command is issued.

The SEE parameter is a rough estimate of the seeing in the CCD image in pixels. This is used by the optimal extraction algorithm for an initial estimate of the FWHM of the point spread function (PSF) during fitting. This parameter defaults to 2 pixels, and again if optimal extraction is not enabled then this parameter will not appear in the list when the options command is issued.

5.1.10 P — photon statistics

This is used to choose between the different ways in which the errors are calculated. There are three possible choices selected by the integers 1 to 4 which have the following meanings :

Errors from photon statistics.
Errors from variations in the sky aperture.
Errors from data variance.
Gaussian errors from variations in the sky aperture.

The first works out the errors from photon statistics in the sky and signal apertures. This requires you to know and set-up the parameters PADU and BIASLE which convert the data values to numbers of photons. The message ‘Errors from photon statistics’ will signify that this has been chosen.

The second method of calculating the errors is from the measured variance in the sky aperture. This method assumes that the measured variance is due to photon statistics and scales the measurement in the object aperture accordingly. This method still requires the parameter PADU to be known, but does not need the BIASLE parameter to be known. The message ‘Errors from sky variance’ will signify that this has been chosen. If neither the PADU or BIASLE parameters are known, then it is best to use this method to indicate the reliability of the measurements, but not to take the quoted error values as absolute since this method will be wrong by a factor PADU, where PADU is the unknown conversion factor.

The third method of calculating the errors is from the data errors that are stored with the image (one per pixel). This method of calculating the errors also requires the parameter PADU to be known. The message ‘Errors from data variance’ will signify that this has been chosen. A variance component may not always be present in data file along with the data array (indeed this can only be true if you are storing your images in NDFs, see section §8), and if this is the case then PHOTOM will issue the warning ‘Data does not have a variance component’ if this method is selected.

The fourth method of calculating the errors is like the second and uses the measured variance in the sky aperture. This method assumes that the measured variance is due to some gaussian source and doesn’t require any knowledge of the PADU and BIASLE values (which are unknown when dealing with data that has been combined using a mean, say from a CCD Mosiac dithered on the sky), but clearly this can only measure an upper limit as the actual noise in the object will be (fractionally) less than in the sky. The best way to avoid such uncertainty is by propagating data variances through all the stages that produced the combined data and using method three.

Appendix D gives a full discussion of the calculation of the errors assuming photon statistics.

5.1.11 S — sky

This is used to choose between the different methods of estimating the background level in the sky aperture. There are four possible choices selected by the integers 1 to 4 which have the following meanings :

Simple mean.
Mean with 2 sigma rejection.
A constant.

The simple mean uses all the values in the sky aperture. The mean with 2 sigma rejection excludes all those points which are more than 2 standard deviations from the mean. Because one or more wayward outliers can affect the size of the standard deviation, the mean and standard deviation are recalculated after each stage of clipping up to a maximum of three times. The mode is superficially calculated from the empirical relation mode = 3 median 2 mean, but because this can be fooled by excessive skewness in the histogram there are rejection and averaging schemes in the algorithm to ensure stability. The final option is to supply a constant for the sky which is used for all subsequent measurements. This value is used until either a new value is chosen or one of the other methods of estimation is selected. The sky variance is also requested so that if the errors are calculated from the sky variance (command P) then a realistic error can be assigned. Both the sky value and variance should be given in data units.

When using a concentric background aperture it is recommended that the mode or mean with 2σ rejection is used as these offer protection against contamination from other objects in the sky aperture.

For optimal extraction it is currently recommended that you use the modal sky estimate.

5.1.12 V — values

This summarizes the current settings of the significant parameters on the terminal.

5.1.13 X – eXtraction

This is a toggle switch which alters the way in which the photometry is carried out. There are two methods available, aperture extraction is the default.

5.2 Defaulted parameters

A number of parameters can only be defined when the PHOTOM program starts. They all have reasonable defaults, but if required can be changed before running the program. The way to set a new value for one of these is to use the keyword (the name by which the parameter is always referred to) on the command line, as in :

  % photom usemags=f resfile=flux.dat

This outputs the values in photon counts (i.e. as modified by the BIASLE and PADU parameters) and writes the results of the analysis to the file flux.dat.

5.2.1 resfile

This specifies the name of the results file which makes a permanent record of the measurements.

5.2.2 maxshift, maxiter, search and toler

There are a number of parameters that control the centroiding algorithm. SEARCH defines the size of the search box to be used in locating the centroid in pixels. MAXITER defines the maximum number of iteration steps. MAXSHIFT gives the maximum allowable shift in pixels between the initial, rough, position and the calculated centroid. TOLER defines the position accuracy in pixels that will terminate the centroiding iterations.

5.2.3 exsource and etime

These two parameters control how a value for the image exposure time is determined. The exposure time is used to scale the results as in:

mag = SKYMAG 2.5 log 10(signal/exposuretime)

This affects the output values for the measured signal in the object and the resultant magnitude or flux, but it does not change the reported value for the sky in each pixel, or the error in the measurement.

There are three methods for getting an exposure time:

supply a floating point value
supply the name of a FITS keyword (which must decode into a floating point value)
supply the name of an HDS object that exists somewhere in your data file that can be decoded as a floating point value (this presumes that you’re storing your images in NDFs).

So for instance if you’ve got an image with a FITS-type header and the exposure time of the image is recorded in the record with name EXPOSURE, then you’d use a command like:

  % photom exsource=header etime=exposure

A simple floating point value (600) is indicated by:

  % photom exsource=constant etime=600

An HDS object ext_time in the CCDPACK extension of an NDF is indicated by:

  % photom exsource=hds etime=more.ccdpack.ext_time

The structure of an NDF can be viewed using the HDSTRACE (SUN/102) utility. The default exposure time is 1.0.

5.2.4 usemask

This parameter is a logical flag which indicates whether a mask is to be used when estimating the background. The purpose of the mask is to block out contaminating objects from the background aperture. In this way bright stars can be excluded from the estimation of the sky, which would otherwise introduce contamination. Note that the sky estimators that perform clipping of the pixel histogram, the mode and the mean with 2σ rejection, also exclude contaminating pixels, but using the mask along with the mean estimator allows this to be done in a controlled way.

If the USEMASK flag is TRUE then a file containing a list of positions is requested (MASKFILE). The format of the file is the same as for inputting a list of positions to measure (command F), namely an index number followed by an x and y position. The given coordinates define the centres of circles and any pixel with its centre within a circle will be excluded from the sky estimation. The radius of the masking circle is defined by another parameter (MASKRAD).

The mask only affects pixels in the background aperture, it does not exclude any pixels from the measurement aperture. This means that identical lists can be used to create the mask and to provide a source for measurement. The output from an automatic object finding package could be used in this way.

It is important not to confuse this mask with the point spread function masks discussed as part of the optimal extraction algorithm.

Other ways of masking out pixels are to use the KAPPA (SUN/95) facilities ARDGEN and ARDMASK, or the ARD and PATCH toolboxes of the GAIA (SUN/214) image display tool.

1At one time this program was the only application in PHOTOM, hence the now slightly confusing terminology.