imfit.py

Go to the documentation of this file.

#
# This file was generated using xslt from its XML file
#
# Copyright 2009, Associated Universities Inc., Washington DC
#
import sys
import os
from  casac import *
import string
from taskinit import casalog
#from taskmanager import tm
import task_imfit
def imfit(imagename='', box='', region='', chans='', stokes='', mask='', includepix=[], excludepix=[], residual='', model='', estimates='', logfile='', append=True, newestimates='', complist='', overwrite=False, dooff=False, offset=0.0, fixoffset=False, stretch=False):

        """Fit one or more elliptical Gaussian components on an image region(s)
PARAMETER SUMMARY
imagename        Name of the input image
box              One or more box regions to use for fitting,
                 eg "100, 120, 200, 220, 300, 300, 400, 400"
                 to use two boxes. If both box and region
                 parameters are specified, box is used.
region           Region of interest. See help par.region for specification options.
stokes           Stokes parameter to fit. If blank, first polarization plane is used.
mask             Mask to use. See help par.mask. Default is none.
includepix       Range of pixel values to include for fitting. Array of two numeric
                 values assumed to have same units as image pixel values. Only one
                 of includepix or excludepix can be specified.
excludepix       Range of pixel values to exclude for fitting. Array of two numeric
                 values assumed to have same units as image pixel values. Only one
                 of includepix or excludepix can be specified.
residual         Name of the residual image to write.
model            Name of the model image to write.
estimates        Name of file containing initial estimates of component parameters
                 (see below for formatting details).
logfile          Name of file to write fit results.
append           If logfile exists, append to it (True) or overwrite it (False).
newestimates     File to write fit results which can be used as initial estimates
                 for next run.
complist         Name of output component list table.
overwrite        Overwrite component list table if it exists?
dooff            Simultaneously fit a zero-level offset?
offset           Initial estimate for the zero-level offset. Only used if dooff is True.
fixoffset        Hold zero-level offset constant during fit? Only used if dooff is True.
stretch          Stretch the input mask if necessary and possible. Only used if a mask is specified.
                 See help par.stretch.

OVERVIEW
imfit is used to fit one or more gaussians to sources in an image as
well as an optional zero-level offset. Fitting is limited to a single polarization
but can be performed over several contiguous spectral channels.
If the image has a clean beam, the report will contain both the convolved
and the deconvolved fit results. It is a simple wrapper around the ia.fitcomponents()
tool method.

When dooff is False, the method returns a dictionary with two keys, 'converged' and 'results'.
The value of 'converged' is a boolean array which indicates if the fit converged
on a channel by channel basis.
The value of 'results' is a dictionary representing a component list reflecting the
fit results. In the case of a deconvolved image, the sizes and position angles are those
of the source convolved with the restoring beam. For convenience, the 'results' dictionary can
be read into a compoenent list tool (default tool is named cl) using the fromrecord() method
for easier inspection using tool methods, eg

cl.fromrecord(res['results'])

If dooff is True, in addtion to the specified number of
gaussians, a zero-level offset will also be fit. The initial estimate for this
offset is specified using the offset parameter. Units are assumed to be the
same as the image brightness units.The zero level offset can be held constant during
the fit by specifying fixoffset=True. In the case of dooff=True, the returned
dictionary contains two additional keys, 'zerooff' and 'zeroofferr', which are both
arrays containing the the fitted zero level offset value and its error, respectively,
for each channel. Both sets of values are in image brightness units.
In cases where the fit did not converge, these values are set to NaN.

The region can either be specified by a box(es) or a region (there is no
garauntee which will be used if both are specified, so be certain only one is).
If specified using the box parameter, multiple boxes can be given using the format
box="blcx1, blcy1, trcx1, trcy1, blcx2, blcy2, trcx2, trcy2, ... , blcxN, blcyN, trcxN, trcyN"
where N is the number of boxes. In this case, the union of the specified boxes will be used.

Ranges of pixel values can be included or excluded from the fit via includepix and excludepix.

If specified, the task will write the residual and/or model images for
successful fits.

If an estimates file is not specified, the task will attempt to estimate
initial parameters and fit a single Gaussian. If a multiple Gaussian fit
is desired, the user must specify initial estimates via a text file
(see below for details).

The user has the option of writing the result of the fit to a log file,
and has the option of either appending to or overwriting an existing file.

The user has the option of writing the (convolved) parameters of a successful
fit to a file which can be fed back to imfit as the estimates file for a
subsequent run.

FITTING OVER MULTIPLE CHANNELS

For fitting over multiple channels, the result
of the previous successful fit is used as the estimate for the next channel. The number
of gaussians fit cannot be varied on a channel by channel basis. Thus the variation
of source structure should be reasonably smooth in frequency to produce reliable fit
results.

MASK SPECIFICATION

Mask specification can be done using an LEL expression. For example

mask = '"myimage">5' will use only pixels with values greater than 5.

INCLUDING AND EXCLUDING PIXELS

Pixels can be included or excluded from the fit based on their values
using includepix and excludepix. Note that specifying both is not permitted
and will result in  an error. If specified, both take an array of two numeric
values.

ESTIMATES

Initial estimates of fit parameters may be specified via an estimates
text file. Each line of this file should contain a set of parameters for
a single gaussian. Optionally, some of these parameters can be fixed during
the fit. The format of each line is

peak intensity, peak x-pixel value, peak y-pixel value, major axis, minor axis, position angle, fixed

The fixed parameter is optional. The peak intensity is assumed to be in the
same units as the image pixel values (eg Jy/beam). The peak coordinates are specified
by pixel values. The major and minor axes and the position angle are the convolved
parameters if the image has been convolved with a clean beam and are specified as quantities.
The fixed parameter is optional and is a string. It may contain any combination of the
following characters 'f' (peak intensity), 'x' (peak x position), 'y' (peak y position),
'a' (major axis), 'b' (minor axis), 'p' (position angle).

In addition, lines in the file starting with a "#" are considered comments.

An example of such a file is:

# peak intensity must be in map units
120, 150, 110, 23.5arcsec, 18.9arcsec, 120deg  
90, 60, 200, 46arcsec, 23arcsec, 140deg, fxp

This is a file which specifies that two gaussians are to be simultaneously fit,
and for the second gaussian the specified peak intensity, x position, and position angle
are to be held fixed during the fit.

ERROR ESTIMATES

The reported estimated errors are the maxima from two methods. In the first method, errors are calculated
according to the description given in AIPS++ Note 224: AIPS++ Least Squares Background available at
http://www.astron.nl/casacore/trunk/casacore/doc/notes/224.html . In the second method (Condon et al
1998AJ.115.1693; Richards et al. 1999MNRAS.306..954), the following algorithms are used to compute the
various errors.

R = rms of residual image
P = fitted peak intensity
S = P/R (signal to noise)

longitude error = (FWHM beam width in longitude direction)/(2*S)
latitude error = (FWHM beam width in latitude direction)/(2*S)
FWHM of major axis error = (FWHM beam along major axis)/S
FWHM of minor axis error = (FWHM beam along minor axis)/S
position angle error is calculated via standard error propogation of the FWHM major and minor axes sizes and errors
flux error is computed via standard error propogation of the peak intensity and its error and the FWHM major
and minor axes sizes and their errors.

In the case where the image has no beam, the pixel width is used as the diameter of the resolution element.

In the vast majority of (and perhaps all) cases, the errors reported come from the second method.

The deconvolved size and position angle errors are computed by taking the maximum of the absolute values of the
differences of the best fit deconvolved value of the given parameter and the deconvolved size of the eight
possible combinations of (FWHM major axis +/- major axis error), (FWHM minor axis +/- minor axis error),
and (position andle +/- position angle error).

CAUTIONARY NOTES ON ERRORS
imfit makes the following implicit assumptions:

1. The noise associated with the pixels it is given to fit is truly random and gaussian
2. There is no offset (constant (unless one is fit), gradient, or more complex function) in pixel values.
3. The things that are trying to be fit are bona-fide gaussians.

If any of these assumptions is not true, the errors reported will in general be lower limits. These
assumptions do not hold if for example, there is structure in the noise of the image (eg the residual map produced
by deconvolution has structure), the area being fit lies in a negative bowl, in extended emission, or on an image
artifact (eg ripple), or the source(s) is nongaussian (eg a disk or more complex function convolved with a gaussian;
just because something looks gaussian to the human image analysis system does not necessarily mean it is).
In addition, in the case of an image produced from interferometric observations, the errors given are appropriate
for good uv plane coverage. They may be a factor of two or more higher for sparse arrays or snapshots.
In short, imfit is not a silver bullet for determining parameters in flawed images and reported errors
should be interpreted cautiously in the vast majority of all "real life" cases. The closer the source being fit is to
fulfilling these assumptions the more realistic reported errors will be.

EXAMPLE: 

Here is how one might fit two gaussians to multiple channels of a cube using the fit
from the previous channel as the initial estimate for the next. It also illustrates
how one can specify a region in the associated continuum image as the region to use
as the fit for the channel.

default imfit
imagename = "co_cube.im"
# specify region using region from continuum
region = "continuum.im:source.rgn"
chans = "2~20"
# only use pixels with positive values in the fit
excludepix = [-1e10,0]
# estimates file contains initial parameters for two Gaussians in channel 2
estimates = "initial_estimates.txt"
logfile = "co_fit.log"
# append results to the log file for all the channels
append = "True"
imfit()


        """
        if type(includepix)==int: includepix=[includepix]
        if type(excludepix)==int: excludepix=[excludepix]

#
#    The following is work around to avoid a bug with current python translation
#
        mytmp = {}

        mytmp['imagename'] = imagename
        mytmp['box'] = box
        mytmp['region'] = region
        mytmp['chans'] = chans
        mytmp['stokes'] = stokes
        mytmp['mask'] = mask
        mytmp['includepix'] = includepix
        mytmp['excludepix'] = excludepix
        mytmp['residual'] = residual
        mytmp['model'] = model
        mytmp['estimates'] = estimates
        mytmp['logfile'] = logfile
        mytmp['append'] = append
        mytmp['newestimates'] = newestimates
        mytmp['complist'] = complist
        mytmp['overwrite'] = overwrite
        mytmp['dooff'] = dooff
        mytmp['offset'] = offset
        mytmp['fixoffset'] = fixoffset
        mytmp['stretch'] = stretch
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'imfit.xml')

        casalog.origin('imfit')
        if trec.has_key('imfit') and casac.utils().verify(mytmp, trec['imfit']) :
            result = task_imfit.imfit(imagename, box, region, chans, stokes, mask, includepix, excludepix, residual, model, estimates, logfile, append, newestimates, complist, overwrite, dooff, offset, fixoffset, stretch)

        else :
          result = False
        return result