STScI Logo

linmatch images.immatch


NAME · USAGE · PARAMETERS · DESCRIPTION · CURSOR_COMMANDS · ALGORITHMS
REFERENCES · EXAMPLES · TIME_REQUIREMENTS · BUGS · SEE_ALSO

NAME

linmatch -- linearly match the intensity scales of 1 and 2D images

USAGE

linmatch input reference regions lintransform

PARAMETERS

input
The list of input images to be matched.
reference
The list of reference images to which the input images are to be matched if scaling is one of the "mean", "median", "mode", or "fit" algorithms, or the list of reference photometry files if scaling specifies the "photometry" algorithm. The number of reference images or reference photometry files must be one or equal to the number of input images.
regions
The list of image regions used to compute the intensity matching function if scaling is one of the "mean", "median", "mode", or "fit" algorithms, or a list of the input photomtry files if scaling specifies the "photometry" algorithm. In the former case regions may be: 1) a string of the form "grid nx ny" defining a grid of nx by ny equally spaced and sized image regions spanning the entire image, 2) a list of object coordinates separated by commas e.g. "303 401, 131 202", 3) a list of image sections separated by whitespace e.g "[101:200,101:200] [301:400,301:400]", 4) the name of a text file containing a list of object coordinates separated by newlines, and 5) the name of a text file containing a list of image sections separated by whitespace and/or newlines.
lintransform
The name of the text file where the computed scaling factors are written. If databasefmt is "yes", a single record containing the computed bscale and bzero factors for each image region or object, and the average bscale and bzero, is written to the text database file for each input image. If databasefmt = "no", a single line containing the input image name, bscale factor, bzero factor, error in bscale, and error in bzero is written to a simple text file for each image.
output = ""
The list of output matched images. If output is the NULL string then bscale and bzero are computed for each input image and written to lintransform , but no output images are written. If output is not NULL then the number of output images must equal the number of input images.
databasefmt = yes
If databasefmt is "yes the computed bscale and bzero factors are written to a text database file, otherwise they are written to a simple text file.
records = ""
The list of records to be written to or read from lintransform one input image. If records is NULL then the output or input record names are assumed to be the names of the input images. If records is not NULL then the record names in records are used to write / read the database records. This parameter is useful for users who, wish to compute the bscale and bzero factors using images that have been processed in some manner (e.g. smoothed), but apply the computed bscale and bzero factors to the original unprocessed images. If more than one record with the same name exists in lintransform then the most recently written record takes precedence. The records parameter is ignored if databasefmt is "no".
append = yes
Append new records to an existing lintransform file or start a new file for each execution of LINMATCH? The append parameter is ignored if databasefmt is "no".
shifts = ""
An optional list of shifts files containing the x and y shifts to be applied to the reference regions to determine their positions in the input images. The number of shifts files must equal the number of reference images. The shifts are listed in the shifts file, 1 shift per line, with the x and y shifts in columns 1 and 2 respectively. If there are fewer x and y shifts defined in the shifts file than there are input images, the extra input images will be assigned x and y shifts of xshift and yshift respectively. The shifts parameter is ignored if the scaling parameter is set to "photometry".
xshift = 0.yshift = 0.0
The default x and y shifts to be be applied to the reference image regions or objects to compute their positions in the input image. Values in shifts take precedence over the values of xshift and yshift . xshift and yshift are ignored if the scaling parameter is set to "photometry".
dnx = dny = 31
The default size of a single image region used to compute the bscale and bzero factors if scaling is one of the the "mean", "median", "mode", or "fit" algorithms and regions is a coordinate list rather than a sections list. dnx and dny are ignored if the scaling parameter is set to "photometry".
maxnregions = 100
The maximum number of image regions or objects with measured photometry that can be used to compute the bscale and bzero factors.
scaling = "mean mean"
The algorithms used to compute the bscale and bzero factors respectively. The options are:
mean median mode
Bscale or bzero are computed using the "mean", "median", or "mode" statistic for each input and reference region individually. If one of the bscale or bzero fitting algorithms is set to "mean", "median", or "mode", the remaining factor must be set to "mean", "median" or "mode" or a numerical constant, e.g. "mean mean", "mean -100.0" or "2.63 mode". If both algorithms are set to "mean", "median", or "mode" bscale will be computed using the specified statistic and bzero will be set to 0.0 If more than one input region is defined then a weighted least squares fit of the reference statistics to the input image statistics is performed and used to compute the final bscale and bzero factors.
fit
Bscale and bzero are computed for each input image region individually by performing a least squares fit of the reference image pixels to the input image pixels. If more than one input image region is defined the final bscale and bzero factors are computed by averaging, weighted by their signal-to-noise ratios, the individual bscale and bzero values. If one of the bscale or bzero fitting algorithms is set to "fit", the remaining factor must either also be computed with the "fit" algorithm or set to a numerical constant, e.g. "fit fit", "fit -100.0", or "2.63 fit".
photometry
Bscale and/or bzero are computed for each input object individually using photometry computed for a set of objects common to the reference and input images. If more than one input object is defined the final bscale and bzero factors are computed by averaging, weighted by their signal-to-noise ratios, the individual bscale and bzero values. If one of the bscale or bzero fitting algorithms is set to "photometry", the remaining factor must either also be computed with the "photometry" algorithm or set to a numerical constant, e.g. "photometry photometry", "photometry -100.0", or "2.63 photometry".
number
Bscale and/or bzero are set to user defined numerical constants, e.g. "2.62 -55.0" or "2.62 median". If both bscale and bzero are numerical constants, LINMATCH must be run in non-interactive mode. If only one of bscale or bzero is a numerical constant, any of the "mean", "median", "mode", "fit", or "photometry" algorithms may be used to compute the remaining factor.
file
Bscale and bzero are not computed but instead read from record record in the text database file lintransform if databasefmt is "yes", or the next line of a simple text file if databasefmt is "no".

Further description of the matching algorithms can be found in the ALGORITHMS section.

datamin = INDEF datamax = INDEF
The minimum and maximum good data values. Datamin and datamax are used by the "mean", "median", and "mode" scaling algorithms to reject entire image regions from the final fit, and by the "fit" algorithm to reject individual bad pixels from the least squares fits for the individual regions.
maxiter = 10
The maximum number of iterations performed by the least squares fitting algorithm.
nreject = 0
The maximum number of rejection cycles used to detect and reject bad pixels from the fit if the scaling algorithm is "fit" or bad regions / objects from the fit if the scaling algorithm is "mean", "median", "mode", "fit", or "photometry".
loreject = INDEF hireject = INDEF
The high- and low-side bad data rejection limits used to detect and reject deviant pixels from the fit if the scaling algorithm is "fit" or bad regions / objects from the fit if the scaling algorithm is "mean", "median", "mode", "fit", or "photometry".
gain = "1.1.0" readnoise = "0.0 0.0"
The reference and input image gain and readout noise in e-/ADU and e- respectively. Gain and readout may be numerical constants or the image header keyword containing the actual gain and/or readout noise value. Gain and readnoise are used by the "mean", "median", "mode", and "fit" algorithms to estimate the expected errors in the computed "mean", "median", or "mode" statistics, and by the "fit" algorithm to compute the per pixel errors values.
interactive = no
Compute the bscale and bzero scaling factors for each image interactively using graphics cursor and optionally image cursor input.
verbose = yes
Print messages about the progress of the task during task execution in non-interactive mode.
graphics = "stdgraph"
The default graphics device.
display = "stdimage"
The default image display device.
gcommands = ""
The default graphics cursor.
icommands = ""
The default image cursor.

DESCRIPTION

LINMATCH computes the bscale and bzero factors required to match the intensity scales of a list of input images input to the intensity scales of a list of reference images reference using the following definition of bscale and bzero and a variety of techniques.

	reference = bscale * input + bzero

The computed bscale and bzero factors are stored in the text file lintransform , in the record records if databasefmt is "yes", or a single line of a simple text file if databasefmt is "no". One record is written to the output file file for each input image. If a non NULL list of output images output is supplied, a scaled output image is written for each input image. LINMATCH is intended to solve 1D and 2D image intensity matching problems where the input and reference images: 1) have the same pixel scale and orientation, 2) differ in intensity by at most a scale factor and a zero point, and 3) contain one or more regions or objects in common that can be used to compute the scaling factors. Some of the scaling algorithms also require that the images registered and have identical point spread functions. LINMATCH cannot be used to compute or apply non-linear intensity matching functions.

If scaling = "mean", "median", "mode", or "fit" bscale and bzero are computed directly from the input and reference image data using the image sections specified in the regions and one of the above fitting techniques as described in the ALGORITHMS section. All four algorithms require accurate knowledge of the measurement errors which in turn require accurate knowledge of the input and reference image gain and readout noise values. Gain and readout noise values can be entered by setting the gain and readnouse parameters to the appropriate numerical values or image header keyword.

Regions is interpreted as either: 1) a string of the form "grid nx ny" specifying a list of nx by ny image sections spanning the entire image, 2) a string defining the coordinates of a list of objects separated by commas e.g. "103.3 189.2, 204.4 389.7", 3) a string containing a list of image sections separated by whitespace, e.g "[100:203,200:300] [400:500,400:500]" 4) the name of a text file containing the coordinates of one or more objects, one object per line, with the x and y coordinates in columns 1 and 2 respectively, 5) the name of a text file containing a list of image sections separated by whitespace and/or newlines. The image sections specifications, or alternatively the object coordinates and the parameters dnx and dny , determine the size of the input and reference image data regions to be extracted and used to compute the bscale and bzero factors. These image regions should be selected with care. Ideal regions span a range of intensity values and contain both object and background data.

If scaling = "photometry", the bscale and bzero factors are computed directly from data in the input and reference image photometry files using the technique described in the ALGORITHMS section. In this case regions is a list of the input image photometry files and reference are the corresponding reference image photometry files written by a separate photometry task. These photometry files are simple text files with the object sky values, errors in the sky values, magnitudes, and errors in the magnitudes in columns 1, 2, 3, and 4 respectively.

An image region is rejected from the fit if it contains data outside the limits specified by the datamin and datamax parameters and scaling = "mean", "median", or "mode". A pixel is rejected from the fit for an individual region if the pixel value is outside the limits specified by datamin and datamax, and the scaling algorithm is "fit". The datamin and datamax parameters are not used by the "photometry" scaling algorithm .

Deviant pixels can be rejected from the fits to individual image regions if scaling = "fit", and nreject , loreject , and hireject are set appropriately. Nreject, loreject and reject are also be used by all the scaling algorithms to reject image regions which contribute deviant bscale and bzero values.

The computed bscale and bzero value for each region and the final bscale and bzero value for each input image are written to the linear transformation file lintransform . If databasefmt is "yes" each result is written to a record whose name is either identical to the name of the input image or supplied by the user via the records parameter . If databasefmt is "no", then a single line containing the input image name and the computed bscale and bzero values and their errors is written to the output shifts file.

If a list of output image names have been supplied then the bscale and bzero values will be applied to the input images to compute the output images.

If the scaling parameter is set to "file" then the shifts computed in a previous run of LINMATCH will be read from the lintransform file and applied to the input images to compute the output images. If no record list is supplied by the user LINMATCH will search for a record whose name is the same as the input image name. If more than one record of the same name is found then the most recently written record will be used.

In non-interactive mode the task parameters are set at task startup time and the input images are processed sequentially. If the verbose flag is set, messages about the progress of the task are printed on the screen as the the task is running.

In interactive mode the user can mark the regions to be used to compute the matching function on the image display, show/set the data and algorithm parameters, compute, recompute, and plot matching function, and interactively delete and undelete bad data from the fits using the plots and graphics cursor. A summary of the available interactive commands is given in the CURSOR COMMANDS section.

CURSOR COMMANDS

The following graphics cursor commands are currently available in LINMATCH.

		Interactive Keystroke Commands

?	Print help 
:	Colon commands

g	Draw a plot of the current fit
i	Draw the residuals plot for the current fit
p	Draw a plot of current photometry
s	Draw histograms for the image region nearest the cursor
l	Draw the least squares fit for the image region nearest the cursor 
h	Draw histogram plot of each image region in turn
l	Draw least squares fits plot of each image region in turn
r	Redraw the current plot
d	Delete the image region nearest the cursor
u	Undelete the image region nearest the cursor
f	Recompute the intensity matching function
w	Update the task parameters
q	Exit


		Colon Commands

:markcoords	    Mark objects on the display
:marksections	    Mark image sections on the display
:show	            Show current values of all the parameters

		Show/set Parameters

:input		[string]    Show/set the current input image
:reference	[string]    Show/set the current reference image / phot file 
:regions	[string]    Show/set the current image regions
:photfile	[string]    Show/set the current input photometry file
:lintransform	[string]    Show/set the linear transform database file name
:dnx		[value]	    Show/set the default x size of an image region
:dny		[value]	    Show/set the default y size of an image region
:shifts		[string]    Show/set the current shifts file
:xshift		[value]     Show/set the input image x shift
:yshift		[value]     Show/set the input image y shift
:output		[string]    Show/set the current output image name
:maxnregions		    Show the maximum number of objects / regions
:gain		[string]    Show/set the gain value / image header keyword
:readnoise	[string]    Show/set the readout noise value / image header
                            keyword

:scaling		    Show the current scaling algorithm
:datamin	[value]     Show/set the minimum good data value
:datamax	[value]     Show/set the maximum good data value
:nreject	[value]	    Show/set the maximum number of rejection cycles
:loreject	[value]     Show/set low side k-sigma rejection parameter
:hireject	[value]     Show/set high side k-sigma rejection parameter

ALGORITHMS

MEAN, MEDIAN, AND MODE

For each input and reference image region the mean, median, mode, statistic and an error estimate for that statistic are computed as shown below, mstat is for mean, median, or mode statistic, emstat stands for the error estimate, stdev for the measured standard deviation, and npix for the number of points.

       mstat = mean, median, or mode 
      emstat = min (sqrt (mean / gain + readnoise ** 2 / gain ** 2),
               stdev / sqrt(npix))

If only a single image region is specified then mstat is used to compute one of bscale or bzero but not both as shown below. Bscale is computed by default.

         bscale = mstat[ref] / mstat[input]
    err[bscale] = abs (bscale) * sqrt (emstat[ref] ** 2 / mstat[ref] ** 2 +
	          emstat[input] ** 2 / mstat[input] ** 2)
	  bzero = constant
     err[bzero] = 0.0

	  bzero = mstat[ref] - mstat[input]
     err[bzero] = sqrt (emstat[ref] ** 2 + emstat[input] ** 2)
	 bscale = constant
    err[bscale] = 0.0

If more than one image region is defined then the computed mean, median, or mode values for the input and reference image regions are used as shown below to compute the bscale and bzero factors and their errors using a weighted least squares fit.

	mstat[ref] = bscale * mstat[input] + bzero

If an image region contains data outside the limits defined by datamin and datamax that image region is eliminated entirely from the fit.

The parameters nreject , loreject , and hireject are used to detect and automatically eliminate deviant data points from the final least squares fit. If for some reason bscale or bzero cannot be fit, default values of 1.0 and 0.0 are assigned.

The mean, median, and mode algorithms depend on the global properties of the image regions. These algorithms do require the reference and input images to have the same pixel scale and orientation, but do not automatically require the reference and input images to have the same point spread function. Small shifts between the reference and input images can be removed using the shifts , xshift , and yshift parameters.

If the image regions contain stars, then either regions should be large enough to include all the flux of the stars in which case the images do not have to have the same psf, or the psfs should be the same so that same portion of the psf is sampled. The best image regions for matching will contain object and background information.

FIT

For each input and reference image the bscale and bzero factors are computed by doing a pixel to pixel weighted least squares fit of the reference image counts to the input image counts as shown below.

    counts[ref] = bscale * counts[input] + bzero
         weight = 1.0 / (err[ref] ** 2 + bscale ** 2 * err[input] ** 2)
       err[ref] = sqrt (counts[ref] / gain[ref] + readnoise[ref] ** 2 /
                  gain[ref] ** 2)
     err[input] = sqrt (counts[input] / gain[input] +
     		  readnoise[input] ** 2 / gain[input] ** 2)

The fitting technique takes into account errors in both the reference and input image counts and provides an error estimate for the computed bscale and bzero factors. Bad data are rejected automatically from the fit by setting the datamin and datamax parameters. Deviant pixels are rejected from the fit by setting the nreject , loreject , and hireject parameters appropriately.

The final bscale and bzero for the input image are computed by calculating the average weighted by their errors of the individual bscale and bzero values. The parameters nreject , loreject , and hirject can be used to automatically detect and reject deviant points.

The fit algorithm depends on the results of pixel to pixel fits in each reference and input image region. The technique requires that the images be spatially registered and psfmatched before it is employed. Each input and reference image should contain a range of pixel intensities so that both bscale and bzero can be accurately determined.

PHOTOMETRY

For each object common to the reference and input photometry files the input sky values sky, errors in the sky values serr, magnitudes mag, and magnitude errors merr are used to compute the bscale and bzero factors and estimate their errors as shown below.

	 bscale = 10.0 ** ((mag[ref] - mag[input]) / 2.5)
	  bzero = sky[ref] - bscale * sky[input]
    err[bscale] = 0.4 * log(10.0) * bscale * sqrt (merr[ref] ** 2 +
		  magerr[input] ** 2)) 
     err[bzero] = sqrt (serr[ref] ** 2 + err[bscale] ** 2 *
                  sky[input] ** 2 + bscale ** 2 * sky[input] ** 2)

The final bscale and bzero for the input image are computed by calculation the average of the individual bscale and bzero values weighted by their errors. The parameters nreject , loreject , and hirject can be used to automatically detect and reject deviant points.

THE LEAST SQUARES FITTING TECHNIQUE

The least squares fitting code performs a double linear regression on the x and y points, taking into account the errors in both x and y.

The best fitting line is the defined below.

		y = a * x + b

The error ellipses are

	S = (x - xfit) ** 2 / err[x] ** 2 + (y - yfit) ** 2 /
	    err[y] ** 2   

where S is the quantity to be minimized. Initial values of a and b are estimated by fitting the data to a straight line assuming uniform weighting. The best fit values of a and b are then determined by iterating on the relationshift

	dy = x' * da + db

where da and db are corrections to the previously determined values of a and b and dy and x' are defined as.

	dy = y - (ax + b)
	x' = x + a * err[x] ** 2 * dy / (a ** 2 * err[x] ** 2 +
	     err[y] ** 2) 

The new values of the a and b then become.

        a = a + da
	b = b + db

REFERENCES

A review of doubly weighted linear regression problems in astronomy can be found in the paper "Linear Regression in Astronomy. II" by (Feigelson and Babu (1992 Ap.J. 397, 55). A detailed derivation of the particular solution used by LINMATCH can be found in the article "The Techniques of Least Squares and Stellar Photometry with CCDs" by Stetson (1989 Proceeding of the V Advanced School of Astrophysics, p 51).

EXAMPLES

1. Match the intensity scales of a list of images to a reference image using a list of stars on the displayed reference image with the image cursor and the "mean" scaling algorithm. Assume that none of the stars are saturated and that a radius of 31 pixels is sufficient to include all the flux from the stars plus some background flux. Make sure that the correct gain and readout noise values are in the image headers.

	cl> display refimage 1 

	cl> rimcursor > objlist
	    ... mark several candidate stars by moving the cursor to the
	        star of interest and hitting the space bar key
	    ... type EOF to terminate the list

	cl> linmatch @imlist refimage objlist lintran.db \
	    out=@outlist dnx=31 dny=31 scaling="mean mean" gain=gain \
	    readnoise=readnoise

2. Repeat the previous command but force the bzero factor to be -100.0 instead of using the fitted value.

	cl> linmatch @imlist refimage objlist lintran.db \
	    out=@outlist dnx=31 dny=31 scaling="mean -100.0" \
	    gain=gain readnoise=rdnoise

3. Repeat the first example but compute bscale and bzero the bscale and bzero values using boxcar smoothed versions of the input images. Make sure the gain and readout noise are adjusted appropriately.

	cl> linmatch @bimlist brefimage objlist lintran.db \
	    dnx=31 dny=31 scaling="mean mean" gain=gain \
	    readnoise=rdnoise

	cl> linmatch @imlist refimage objlist lintran.db \
	    out=@outimlist records=@bimlist scaling="file file"

4. Match the intensity of an input image which has been spatially registered and psfmatched to the reference image using the "fit" algorithm and a single reference image region. Remove the effects of saturated pixels by setting datamax to 28000 counts, and the effects of any deviant pixels by setting nreject, loreject, and hireject to appropriate values.

	cl> linmatch image refimage [50:150,50:150] lintran.db \
	    out=outimage scaling="fit fit" datamax=28000 nreject=3 \
	    loreject=3 hireject=3 gain=gain readnoise=rdnoise

5. Repeat the previous example but use several image sections to compute the bscale and bzero values.

	cl> linmatch image refimage sections lintran.db \
	    out=outimage scaling="fit fit" datamax=28000 nreject=3 \
	    loreject=3 hireject=3 gain=gain readnoise=rdnoise

6. Match the intensity scales of two images using photometry computed with the apphot package qphot task. The two images are spatially registered, psfmatched, and the photometry aperture is sufficient to include all the light from the stars. The filecalc task used to compute the error in the mean sky is in the addon ctio package.

	cl> display refimage 1 fi+
	cl> rimcursor > objlist
	    ... mark several candidate stars by moving the cursor to the
	        star of interest and hitting the space bar key
	    ... type EOF to terminate the list
	cl> qphot refimage coords=objlist inter-
	cl> qphot image coords=objlist inter-
	cl> pdump refimage.mag.1 msky,stdev,nsky,mag,merr yes | filecalc \
	    STDIN "$1;$2/sqrt($3);$4;$5" > refimage.phot
	cl> pdump image.mag.1 msky,stdev,nsky,mag,merr yes | filecalc \
	    STDIN "$1;$2/sqrt($3);$4;$5" > image.phot
	cl> linmatch image refimage.phot image.phot lintran.db \
	    out=outimage scaling="phot phot" nreject=3 loreject=3\
	    hireject=3

7. Register two images interactively using the fit algorithms and five non-overlapping image regions in the sections file.

	cl> linmatch image refimage sections lintran.db \
	    out=outimage scaling="fit fit" datamax=28000 nreject=3 \
	    loreject=3 hireject=3 gain=gain readnoise=rdnoise \
	    interactive +

	    ... a plot of bscale and bzero versus region number
		appears

	    ... type ? to get a list of the keystroke and : commands

	    ... type i to see a plot of the bscale and bzero residuals
		versus region

	    ... type g to return to the default bscale and bzero versus
		region plot

	    ... type l to examine plot of the fits and residuals for the
		individual regions
		... step forward and back in the regions list with the
		space bar and -keys
		... flip back and forth between the fit and residuals
		keys with l and i keys
		... return to the main plot by typing q

	    ... return to the residuals plot by typing i and delete a
		region with a large residual by moving to the
		bad point and typing d

	    ... type f to recompute the fit

	    ... type q to quit the interactive loop, n to go to the
		next image or q to quit the task
		

TIME REQUIREMENTS

BUGS

SEE ALSO

imexpr, imcombine, ctio.filecalc, apphot.qphot, apphot.phot


Source Code · Search Form · STSDAS