setaper for setting up photometric apertures

setaper is an interactive program for defining photometric apertures. It requires a data frame to exist. It uses 3 circles, one for the target and two to define an annulus for the sky centred on it. It dumps an ASCII file, which can be edited directly if desired and you know what you are doing.

When creating a file you will be asked to define the radii. These will be kept fixed unless you specifically request a change. For an old file, the radii will be taken from the first aperture.

The general idea is to place the cursor at a position or aperture that you want to do something at/to, and then to hit the appropriate letter.

setaper supports the addition of sky masks attached to the individual apertures. These are so that if there are stars contaminating the sky annulus you can remove them rather than relying upon the sky estimator to do it for you. Here is an example of what this can look like. See at the end of this help for an even more complex case which shows what one can do.

setaper also supports the addition of extra apertures to attach to a given aperture. These are region that you want to include along with your main target. They provide a mechanism to include nearby stars when not including them could affect photometry.

Creation of an aperture file is needed for the main reduction program reduce. It might be worth your reviewing the options supported in reduce to work out how you set up your aperture file. Some options for instance require that you define reference stars.

Various options move or delete apertures. There is no good way to do this graphically and so I just overplot in red. This can end up looking confusing in which case a replot can be a good idea at times (e.g. with 'W').

Invocation

setaper [device] data newfile aper (rstar rsky1 rsky2) nccd xleft xright ylow yhigh iset (ilow ihigh)/(plow phigh) refine [fwhm hwidth readout gain symm (beta) sigrej onedsrch (fwhm1d hwidth1d) fdevice]

Command line arguments

device --- The image display device.

data --- Ultracam data file.

newfile --- flag to indicate that the aperture file is new.

aperture --- Aperture file (new or old).

rstar --- If the aperture file is new, you will be prompted to specify the radius of the star aperture. There is also an interactive option to change this radius during the routine.

rsky1 --- If the aperture file is new, you will be prompted to specify the inner radius of the sky annulus

rsky2 --- If the aperture file is new, you will be prompted to specify the outer radius of the sky annulus

nccd --- The number of the CCD to set apertures over.

xleft xright --- X range to plot

ylow yhigh --- Y range to plot

iset --- How to set intensity: 'a' for automatic, min to max, 'd' for direct input of range, 'p' for percentiles, probably the most useful option.

ilow ihigh --- the intensity range is i1 to i2 if iset='d'

plow phigh --- p1 to p2 are percentiles to set the intensity if iset = 'p'

refine --- One selects positions byt cursor, but these can be refined automatically by C(entroiding) which uses a simple cross-correlation with a gaussian of the projections around the star in /x and Y, G(aussian) which fits 2D gaussian profiles, M(offat) which fits 2D Moffat profiles or N(one) which just takes the raw positions. For both gaussian and moffat fits there is also the option of an initial centroid. The many other arguments associated with refining are hidden by default.

fwhm --- This is the first of several parameters associated with profile fits (gaussian or moffat profiles). fwhm is the initial FWHM to use in either case.

hwidth --- The half-width of the region to be used when fitting a target. Should be larger than the fwhm, but not so large as to include multiple targets if possible.

readout --- Readout noise, RMS ADU in order for the program to come back with an uncertainty.

gain --- Gain, electrons/ADU, again for uncertainty estimates

symm --- Yes/no for symmetric versus ellliptical profile fits

beta --- The beta parameter of the moffat fits.

sigrej --- The fits can include rejection of poor pixels. This is the threshold, meaured in sigma. Should not be too small.

onedsrch --- Yes if you want an initial 1D search to be made. This is tolerant of poor positioning of the start point, but potentially vulnerable to problems with multiple targets. What happens is that a box around the cursor position is collpased in X and Y and then the peak in each direction is located using cross-correlation with a gaussian of FWHM=fwhm1D. This new position is then used to define the fitting region and initial position for the 2D gaussian fit.

fwhm1d --- This is the FWHM used in the 1D search. It does not have to match the FWHM of the target necessarily. In particular a somewhat larger value is less sensitive to initial position errors.

hwidth1d --- The half-width of the region to be used for searching for a target. The wider this is, the more chance of finding a target from a sloppy start position, but also the more chance of peaking up on a spurious target.

fdevice --- Plot device for showing Moffat & symmetrical gaussian fits. Should be different from the image plot device. e.g. "/xs" or "2/xs" if image plot device = "1/xs" otherwise the program will go belly up for reasons that I cannot quite track down. 'null' to ignore.

Interactive options

There are several interactive options, all single letters, which are as follows:

A(dd)	---	Adds a new aperture at the cursor position.
B(reak)	---	Break the link on an aperture. i.e. restore it to its usual state without deleteing it.
C(entre)	---	Centre an aperture using whatever centering option is current. Aperture selected with 'A' will be centred, but this option allows an aperture to be re-centred, for instance after some sky masks have been added to it, or for a small shift in the image position. NB the current aperture position is used as the start position, not the cursor position which is used only to select the aperture to center.
E(xtra)	---	Adds or removes extra star apertures associated with a given aperture. The purpose is to help when there is a close by styar that for best photometry you might as well include.
F(ull)	---	Display the full frame.
I(n)	---	Zooms in by a factor 2 around the cursor position.
L(ink)	---	Links two apertures. When determining the position of a target, it will often make sense to do so using a nearby brighter star which is less likely to be upset by poor signal, cosmic rays etc. To do this place the cursor near to the potentially feeble star and hit 'L'. You will then be prompted to specify the 'master target' that you want to link to. NB Really you are linking the 'slave' to the position of target aperture, not anything else. Thus it is quite permissible to delete the master aperture, if for instance you only wanted to use it for positioning and not photometry. Similarly, there is nothing to prevent deletion of the 'slave'.
M(ask)	---	Mask a star from the sky annulus of an aperture. You need to click near the relevant aperture, then at the position of the star to be masked (it will not be centroided), and then at the radius wanted for the mask. This should be done at reasonably high zoom for best results. The masks can be removed with 'U'.
N(ew)	---	New aperture radii.
O(ut)	---	Zooms out by a factor 2 around the cursor position.
Q(uit)	---	Quit the program.
R(emove)	---	Remove an aperture. Place the cursor near to the aperture you want to remove and then hit 'R'.
S(et)	---	Set/unset an aperture as a reference star. This is in order to support the aperture moving options of reduce and for the profile fitting used in optimal and variable aperture extraction.
U(nmask)	---	Removes a mask from an aperture.
W(indow)	---	Define a window with the cursor which will then be displayed

Complex example of an aperture file

This complex example shows a case with dummy apertures (5, 7, 8) to calibrate the scattered light from a bright star that will affect the main target (aperture 1). Each of these must be linked because, since they have no star, no position can be determined. Each of them also has a mask to exclude some of the scattered light. Other apertures are set on comparison stars. Aperture 2 is placed upon the brightest available comparison which will be uased as a reference. There are some useful scripts for developing such apertures: dummy and copymask.

Classes

This command is a member of the classes: Programs, Setup.

Author: T.R. Marsh
Created: 17 May 2001
Revised: 09 June 2004

Page generated Fri Jul 5 12:23:42 2013

device	---	The image display device.
data	---	Ultracam data file.
newfile	---	flag to indicate that the aperture file is new.
aperture	---	Aperture file (new or old).
rstar	---	If the aperture file is new, you will be prompted to specify the radius of the star aperture. There is also an interactive option to change this radius during the routine.
rsky1	---	If the aperture file is new, you will be prompted to specify the inner radius of the sky annulus
rsky2	---	If the aperture file is new, you will be prompted to specify the outer radius of the sky annulus
nccd	---	The number of the CCD to set apertures over.
xleft xright	---	X range to plot
ylow yhigh	---	Y range to plot
iset	---	How to set intensity: 'a' for automatic, min to max, 'd' for direct input of range, 'p' for percentiles, probably the most useful option.
ilow ihigh	---	the intensity range is i1 to i2 if iset='d'
plow phigh	---	p1 to p2 are percentiles to set the intensity if iset = 'p'
refine	---	One selects positions byt cursor, but these can be refined automatically by C(entroiding) which uses a simple cross-correlation with a gaussian of the projections around the star in /x and Y, G(aussian) which fits 2D gaussian profiles, M(offat) which fits 2D Moffat profiles or N(one) which just takes the raw positions. For both gaussian and moffat fits there is also the option of an initial centroid. The many other arguments associated with refining are hidden by default.
fwhm	---	This is the first of several parameters associated with profile fits (gaussian or moffat profiles). fwhm is the initial FWHM to use in either case.
hwidth	---	The half-width of the region to be used when fitting a target. Should be larger than the fwhm, but not so large as to include multiple targets if possible.
readout	---	Readout noise, RMS ADU in order for the program to come back with an uncertainty.
gain	---	Gain, electrons/ADU, again for uncertainty estimates
symm	---	Yes/no for symmetric versus ellliptical profile fits
beta	---	The beta parameter of the moffat fits.
sigrej	---	The fits can include rejection of poor pixels. This is the threshold, meaured in sigma. Should not be too small.
onedsrch	---	Yes if you want an initial 1D search to be made. This is tolerant of poor positioning of the start point, but potentially vulnerable to problems with multiple targets. What happens is that a box around the cursor position is collpased in X and Y and then the peak in each direction is located using cross-correlation with a gaussian of FWHM=fwhm1D. This new position is then used to define the fitting region and initial position for the 2D gaussian fit.
fwhm1d	---	This is the FWHM used in the 1D search. It does not have to match the FWHM of the target necessarily. In particular a somewhat larger value is less sensitive to initial position errors.
hwidth1d	---	The half-width of the region to be used for searching for a target. The wider this is, the more chance of finding a target from a sloppy start position, but also the more chance of peaking up on a spurious target.
fdevice	---	Plot device for showing Moffat & symmetrical gaussian fits. Should be different from the image plot device. e.g. "/xs" or "2/xs" if image plot device = "1/xs" otherwise the program will go belly up for reasons that I cannot quite track down. 'null' to ignore.