CApphot:SetBgMethod

The SetBgMethod method sets the method used to remove the background from the photometric measurement. The options are "mean", "median", "mode", and "value". When a new CApphot object is created (not copied), the default background method is set to "mode" with a skew of 1 (positive). If the "Value" method is selected, then the background value and it error must also be specified using this method.

Syntax

CApphot:SetBgMethod( sMethod )

CApphot:SetBgMethod( sMethod, nBgValue )

CApphot:SetBgMethod( sMethod, nBgValue, nBgError )

where

sMethod is a string describing the background method.

nBgValue is the fist optional parameter. If sMethod is mode, this is the skew parameter (-1, 0, or 1). If sMethod is value, this is the background value. It is ignored for the mean and median methods.

nBgError is the second optional parameter that specifies the uncertainty in nBgValue. It is used only for the value method and defaults to 0 if not specified.

The background method describes the way the local image background is estimated underneath the object. This background is computed using the value of pixels in the annulus (ring) between nRadius2 and nRadius3. These values are combined using a selected method to derive a single value for the background. If the sample contains random noise scattered about the true background value, then the distribution of background values is symmetric and the calculated value refers to the peak of the distribution. Frequently, however, the background annulus will include another object, such as a star, which skews the distribution of pixel values toward large positive values. In such cases, the correct background value is still near the peak of the distribution but various methods of calculating the background will not necessarily give a good estimate of the correct, but unknown, value. These methods are available:

Background Methods

mean	The mean method is good when the the background sample is not biased by objects appearing in the background annulus. Objects in the sample bias the mean value toward a higher value. However, the mean benefits from giving a value that is fractional between the actual pixel values.
median	The median method rejects outlying pixels appearing in the background sample but still can leave a small residual bias toward the direction of preference (toward higher values if an object appears in the background annulus). However, the median has the fault that it is quantized to one of the pixel values found in the pixel sample and cannot refine the background estimate to a fractional value in the way the mean method can do.
mode	The mode method provides more freedom from skew bias similar to the median method, but also gives a non-quantized value like the mean. The mode method can also be tuned by using the optional nBgValue parameter to specify the skew direction.
value	The value method allows you to specify the background. For example, you may estimate the background using methods in the CStats class. In this case, the optional nBgValue parameter is required and the nBgError parameter may be specified to include the uncertainty in the background value (use the 1-sigma mean error in the value, not the error of the mean value).

The method used to combine the background pixel sample into a single value are described in the following table. Note that the value is case sensitive; for example, use "mean" rather than "MEAN".

Examples Using Optional Parameters

These examples show how the 1 or optional parameters are used with the mode method.

Median method: SetBgMethod( "median" )

Mode method with skew parameter 0: SetBgMethod( "mode", 0 )

Mode method with skew parameter 1: SetBgMethod( "mode", 1 )

Value method with value and error: SetBgMethod( "value", 2492.4, 10.5 )

Setting the Skew Direction for the Mode Method

When selecting the Mode option, the first optional parameter specifies the skew direction. This value gives more reliable rejection of non-random values by hinting at the preferred direction of the skew in the pixel value distribution. When making astronomical measurements, the skew is almost always toward the positive direction, so this is the default setting if you do not specify it. The options are described in the following table.

1	Specifies that non-random values have a preference for the positive direction (brighter than the background). This is the default when the skew direction parameter is not set.
-1	Specifies that non-random values have a preference for the negative direction (fainter than the background).
0	Specifies that non-random values have no preference so that the distribution is symmetric about the background value.

Example

The following script uses SetBgMethod to specify that the background is measured using the mode of pixels in the annulus between nRadius2=12 and nRadius3=16 pixels.

A = CApphot:new()	-- create a CApphot object
A.nRadius1 = 4.5	-- Set the value of nRadius1
A.nRadius2 = 12	-- Set the value of nRadius2
A.nRadius3 = 16	-- Set the value of nRadius3

A.SetBgMethod("median")	-- Set median method
bSuccess = A:Measure(I,x,y)	-- Measure object at (x,y) in CImage I
Printf("Mag = %lg", A.nMag )	-- result: Mag = 15.332

A.SetBgMethod("mode")	-- Set mode method, default to positive skew
bSuccess = A:Measure(I,x,y)	-- Measure object at (x,y) in CImage I
Printf("Mag = %lg", A.nMag )	-- result: Mag = 15.256

A.SetBgMethod("value",242.5,8.5)	-- Set value method with value and error
bSuccess = A:Measure(I,x,y)	-- Measure object at (x,y) in CImage I
Printf("Mag = %lg", A.nMag )	-- result: Mag = 15.154