NRAO Home > CASA > CASA Task Reference Manual

0.1.105 sdfitold

Requires:

Synopsis
Fit a spectral line

Description

Task sdfitold is a basic line-fitter for single-dish spectra. It assumes that the spectra have been calibrated in sdcal or sdreduce.

Arguments





Outputs

xstat

RETURN ONLY: a Python dictionary of line statistics

allowed:

any

Default:

variant

Inputs

infile

name of input SD dataset

allowed:

string

Default:

antenna

select an antenna name or ID, e.g. ’PM03’ (only effective for MS input)

allowed:

any

Default:

variant 0

fluxunit

units of the flux (”=current)

allowed:

string

Default:

telescopeparam

parameters of telescope for flux conversion (see examples in help)

allowed:

any

Default:

variant

field

select data by field IDs and names, e.g. ’3C2*’ (”=all)

allowed:

string

Default:

spw

select data by IF IDs (spectral windows), e.g. ’3,5,7’ (”=all)

allowed:

string

Default:

restfreq

the rest frequency, e.g. ’1.41GHz’ (default unit: Hz) (see examples in help)

allowed:

any

Default:

variant

frame

frequency reference frame (”=current)

allowed:

string

Default:

doppler

doppler convention (”=current). Effective only when spw selection is in velocity unit.

allowed:

string

Default:

scan

select data by scan numbers, e.g. ’21~23’ (”=all)

allowed:

string

Default:

pol

select data by polarization IDs, e.g. ’0,1’ (”=all)

allowed:

string

Default:

timeaverage

average spectra over time (see examples in help)

allowed:

bool

Default:

False

tweight

weighting for time averaging

allowed:

string

Default:

tintsys

scanaverage

average spectra within a scan number (see examples in help)

allowed:

bool

Default:

False

polaverage

average spectra over polarizations

allowed:

bool

Default:

False

pweight

weighting for polarization averaging

allowed:

string

Default:

tsys

fitfunc

function for fitting

allowed:

string

Default:

gauss

fitmode

mode for fitting

allowed:

string

Default:

auto

nfit

list of number of gaussian/lorentzian lines to fit in in maskline region (ignored when fitmode=”auto”)

allowed:

intArray

Default:

thresh

S/N threshold for linefinder

allowed:

double

Default:

5.0

min_nchan

minimum number of consecutive channels for linefinder

allowed:

int

Default:

3

avg_limit

channel averaging for broad lines

allowed:

int

Default:

4

box_size

running mean box size

allowed:

double

Default:

0.2

edge

channels to drop at beginning and end of spectrum

allowed:

intArray

Default:

0

outfile

name of output file (See a WARNING in help)

allowed:

string

Default:

overwrite

overwrite the output file if already exists

allowed:

bool

Default:

False

plotlevel

control for plotting of results (see examples in help)

allowed:

int

Default:

0

Returns
variant

Example

 
-----------------  
Keyword arguments  
-----------------  
infile -- name of input SD dataset  
antenna -- select an antenna name or ID  
        default: 0  
        example: ’PM03’  
        NOTE this parameter is effective only for MS input  
fluxunit -- units for line flux  
        options: ’K’,’Jy’,’’  
        default: ’’ (keep current fluxunit in data)  
        WARNING: For GBT data, see description below.  
    >>> fluxunit expandable parameter  
        telescopeparam -- parameters of telescope for flux conversion  
                options: (str) name or (list) list of gain info  
                default: ’’ (none set)  
                example: if telescopeparam=’’, it tries to get the telescope  
                         name from the data.  
                         Full antenna parameters (diameter,ap.eff.) known  
                         to ASAP are  
                         ’ATPKSMB’, ’ATPKSHOH’, ’ATMOPRA’, ’DSS-43’,  
                         ’CEDUNA’,’HOBART’. For GBT, it fixes default fluxunit  
                         to ’K’ first then convert to a new fluxunit.  
                         telescopeparam=[104.9,0.43] diameter(m), ap.eff.  
                         telescopeparam=[0.743] gain in Jy/K  
                         telescopeparam=’FIX’ to change default fluxunit  
                         see description below  
field -- select data by field IDs and names  
        default: ’’ (use all fields)  
        example: field=’3C2*’ (all names starting with 3C2)  
                 field=’0,4,5~7’ (field IDs 0,4,5,6,7)  
                 field=’0,3C273’ (field ID 0 or field named 3C273)  
        this selection is in addition to the other selections to data  
spw -- select data by IF IDs (spectral windows)/channels  
        default: ’’ (use all IFs and channels)  
        example: spw=’3,5,7’ (IF IDs 3,5,7; all channels)  
                 spw=’<2’ (IF IDs less than 2, i.e., 0,1; all channels)  
                 spw=’30~45GHz’ (IF IDs with the center frequencies in range 30-45GHz; all channels)  
                 spw=’0:5~61’ (IF ID 0; channels 5 to 61; all channels)  
                 spw=’3:10~20;50~60’ (select multiple channel ranges within IF ID 3)  
                 spw=’3:10~20,4:0~30’ (select different channel ranges for IF IDs 3 and 4)  
                 spw=’1~4;6:15~48’ (for channels 15 through 48 for IF IDs 1,2,3,4 and 6)  
        this selection is in addition to the other selections to data  
    >>> spw expandable parameter  
        restfreq -- the rest frequency  
                    available type includes float, int, string, list of float,  
                    list of int, list of string, and list of dictionary. the  
                    default unit of restfreq in case of float, int, or string  
                    without unit is Hz. string input can be a value only  
                    (treated as Hz) or a value followed by unit for which ’GHz’,  
                    ’MHz’,’kHz’,and ’Hz’ are available.  
                    a list can be used to set different rest frequencies for  
                    each IF. the length of list input must be number of IFs.  
                    dictionary input should be a pair of line name and  
                    frequency with keys of ’name’ and ’value’, respectively.  
                    values in the dictionary input follows the same manner as  
                    as for single float or string input.  
                example: 345.796  
                         ’1420MHz’  
                         [345.8, 347.0, 356.7]  
                         [’345.8MHz’, ’347.0MHz’, ’356.7MHz’]  
                         [{’name’:’CO’,’value’:345}]  
        frame -- frequency reference frame  
                options: ’LSRK’, ’TOPO’, ’LSRD’, ’BARY’, ’GALACTO’, ’LGROUP’, ’CMB’  
                default: ’’ (keep current frame in data)  
        doppler -- doppler convention (effective only when spw is in  
                   velocity unit)  
                options: ’RADIO’, ’OPTICAL’, ’Z’, ’BETA’, or ’GAMMA’  
                default: ’’ (keep current doppler setting in data)  
scan -- select data by scan numbers  
        default: ’’ (use all scans)  
        example: scan=’21~23’ (scan IDs 21,22,23)  
        this selection is in addition to the other selections to data  
pol -- select data by polarization IDs  
        default: ’’ (use all polarizations)  
        example: pol=’0,1’ (polarization IDs 0,1)  
        this selection is in addition to the other selections to data  
fitfunc -- function for fitting  
        options: ’gauss’ (Gaussian), ’lorentz’ (Lorentzian)  
        default: ’gauss’  
fitmode -- mode for fitting  
        options: ’auto’, ’list’, or ’interact’  
        default: ’auto’  
        example: ’auto’ will use the linefinder to fit for lines  
                        using the following parameters  
                 ’list’ will use maskline to define regions to  
                        fit for lines with nfit in each  
                 ’interact’ allows adding and deleting mask  
                        regions by drawing rectangles on the plot  
                        with mouse. Draw a rectangle with LEFT-mouse  
                        to ADD the region to the mask and with RIGHT-mouse  
                        to DELETE the region.  
 
    >>> fitmode expandable parameters  
        thresh -- S/N threshold for linefinder. a single channel S/N ratio  
                  above which the channel is considered to be a detection.  
                default: 5  
        min_nchan -- minimum number of consecutive channels required to  
                     pass threshold  
                       default: 3  
        avg_limit -- channel averaging for broad lines. a number of  
                     consecutive channels not greater than this parameter  
                     can be averaged to search for broad lines.  
                default: 4  
        box_size -- running mean box size specified as a fraction  
                    of the total spectrum length  
                default: 0.2  
        edge -- channels to drop at beginning and end of spectrum  
                default: 0  
                example: edge=[1000] drops 1000 channels at beginning AND end.  
                         edge=[1000,500] drops 1000 from beginning and 500  
                         from end  
 
        Note: For bad baselines threshold should be increased,  
        and avg_limit decreased (or even switched off completely by  
        setting this parameter to 1) to avoid detecting baseline  
        undulations instead of real lines.  
 
nfit -- list of number of gaussian/lorentzian lines to fit in in maskline  
        region (ignored when fitmode=’auto’)  
        default: 0 (no fitting)  
        example: nfit=[1] for single line in single region,  
                 nfit=[2] for two lines in single region,  
                 nfit=[1,1] for single lines in each of two regions, etc.  
outfile -- name of output file  
        default: no output fit file  
        example: ’mysd.fit’  
overwrite -- overwrite the output file if already exists  
        options: (bool) True, False  
        default: False  
plotlevel -- control for plotting of results  
        options: 0, 1, 2  
        default: 0 (no plotting)  
        example: plotlevel=0 no plotting  
                 plotlevel=1 plots fit  
                 plotlevel=2 plots fit and residual  
                 no hardcopy available for fitter  
        WARNING: be careful plotting OTF data with lots of fields  
 
-------  
Returns  
-------  
a Python dictionary of line statistics  
    keys: ’peak’, ’cent’, ’fwhm’, ’nfit’  
    example: each value is a list of lists with one list of  
             2 entries [fitvalue,error] per component.  
             e.g. xstat[’peak’]=[[234.9, 4.8],[234.2, 5.3]]  
             for 2 components.  
 
-----------  
DESCRIPTION  
-----------  
 
Task sdfitold is a basic line-fitter for single-dish spectra.  
It assumes that the spectra have been calibrated in sdcal  
or sdreduce.  
 
Furthermore, it assumes that any selection of scans, IFs,  
polarizations, and time and channel averaging/smoothing has  
also already been done (in other sd tasks) as there are no controls  
for these.  Note that you can use sdsave to do selection, writing  
out a new scantable.  
 
Note that multiple scans, IFs, and polarizations can in principle  
be handled, but we recommend that you use scan, field, spw, and pol  
to give a single selection for each fit.  
 
Currently, you can choose Gaussian or Lorentzian profile as a  
fitting model.  
 
For complicated spectra, sdfitold does not do a good job of  
"auto-guessing" the starting model for the fit.  We recommend  
you use sd.fitter in the toolkit which has more options, such  
as fixing components in the fit and supplying starting guesses  
by hand.  
 
-------  
FITMODE  
-------  
As described in the parameter description section, sdfitold implements  
three fitting mode, ’auto’, ’list’, and ’interact’. Only difference  
between these modes are a method to set initial guess for line fitting.  
In ’auto’ mode, initial guess is automatically set by executing line  
finder. On the other hand, ’list’ and ’interact’ allow to set initial  
guess manually. In these modes, only controllable parameter for the  
guess is range of the line region and number of lines per region.  
In ’list’ mode, the user must give line region via spw parameter by using  
ms selection syntax while number of lines per region can be specified  
via nfit parameter. For example,  
 
    spw = ’17:1500~2500’  
    nfit = [1]  
 
will set line region between channels 1500 and 2500 for spw 17, and  
indicate that there is only one line in this region. Specifying single  
region with multiple line is also possible but is not recommended.  
In ’interact’ mode, spectral data to be fitted will be displayed  
with pre-defined line region specified by spw parameter. The user is  
able to customize line region interactively.  
 
--------------------  
FLUX UNIT CONVERSION  
--------------------  
The task is able to convert flux unit between K and Jy. To do that,  
fluxunit and its subparameter telescopeparam must be properly set.  
The fluxunit should be ’Jy’ or ’K’ depending on what unit input data  
is and what unit you want to convert. If given fluxunit is different  
from the unit of input data, unit conversion is performed.  
The telescopeparam is used to specify conversion factor. There are three  
ways to specify telescopeparam: 1) set Jy/K conversion factor, 2) set  
telescope diameter, D, and aperture efficiency, eta, separately, and  
3) ’FIX’ mode (only change the unit without converting spectral data).  
If you give telescopeparam as a list, then if the list has a single float  
it is assumed to be the gain in Jy/K (case 1), if two or more elements  
they are assumed to be telescope diameter (m) and aperture efficiency  
respectively (case 2).  
See the above parameter description as well as note on ’FIX’ mode below  
for details.  
 
There are two special cases that don’t need telescopeparam for unit  
conversion. Telescope name is obtained from the data.  
1) ASAP (sd tool) recognizes the conversion factor (actually D and  
   eta) for the "AT" telescopes, namely ATNF MOPRA telescope, until  
   2004.  
2) The task does know D and eta for GBT telescope.  
If you wish to change the fluxunit, by leaving the sub-parameter  
telescopeparam unset (telescopeparam=’’), it will use internal telescope  
parameters for flux conversion for the data from AT telescopes and it  
will use an approximate aperture efficiency conversion for the GBT data.  
 
Note that sdcal assumes that the fluxunit is set correctly in the data  
already. If not, then set telescopeparam=’FIX’ and it will set the  
default units to fluxunit without conversion.  
Note also that, if the data in infile is an ms from GBT and the default  
flux unit is missing, this task automatically fixes the default fluxunit  
to ’K’ before the conversion.  
 
-------------------------------------  
AVERAGING OF SPECTRA  
-------------------------------------  
Task sdfitold has two averaging modes, i.e., time and polarization average.  
 
When timeaverage=True, spectra are averaged over time for each IF  
(spectral window), polarization, and beam, independently. Note that,  
by default (scanaverage=False), timeaverage=True averages spectra  
irrespective of scan IDs.  
It is possible to average spectra separately for each scan ID by setting  
a sub-parameter scanaverage=True.  
For example, the combination of parameters: scan=’0~2’, timeaverage=True, and  
scanaverage=False: averages spectra in scan ID 0 through 2 all together  
                   to a spectrum,  
scanaverage=True : averages spectra per scan ID and end up with three  
                   spectra from scan 0, 1, and 2.  
 
When polaverage=True, spectra are averaged over polarization for  
each IF (spectral window) and beam. Note that, so far, time averaging is  
automatically switched on when polaverage is set to True. This behavior  
is not desirable and will be discarded in future.  
 
-------  
WARNING  
-------  
For the GBT raw SDFITS format data as input:  
SDtasks are able to handle GBT raw SDFITS format data since the data  
filler is available. However, the functionality is not well tested yet,  
so that there may be unknown bugs.  


More information about CASA may be found at the CASA web page

Copyright 2016 Associated Universities Inc., Washington, D.C.

This code is available under the terms of the GNU General Public Lincense


Home | Contact Us | Directories | Site Map | Help | Privacy Policy | Search