Source code for casatasks.single.sdfit

#
# stub function definition file for docstring parsing
#

[docs]def sdfit(infile, datacolumn='data', antenna='', field='', spw='', timerange='', scan='', pol='', intent='', timebin='', timespan='', polaverage='', fitfunc='gaussian', fitmode='list', nfit=[0], thresh=5.0, avg_limit=4, minwidth=4, edge=[0, 0], outfile='', overwrite=False): r""" Fit a spectral line [`Description`_] [`Examples`_] [`Development`_] [`Details`_] Parameters - infile_ (path) - name of input SD dataset - datacolumn_ (string='data') - name of data column to be used ["data", "float_data", or "corrected_data"] - antenna_ (string='') - select data by antenna name or ID, e.g. "PM03" - field_ (string='') - select data by field IDs and names, e.g. "3C2*" (""=all) - spw_ (string='') - select data by IF IDs (spectral windows), e.g. "3,5,7" (""=all) - timerange_ (string='') - select data by time range, e.g. "09:14:0~09:54:0" (""=all) (see examples in help) - scan_ (string='') - select data by scan numbers, e.g. "21~23" (""=all) - pol_ (string='') - select data by polarization IDs, e.g. "XX,YY" (""=all) - intent_ (string='') - select data by observational intent, e.g. "*ON_SOURCE*" (""=all) - timebin_ (string='') - bin width for time averaging .. raw:: html <details><summary><i> timebin != '' </i></summary> - timespan_ (string='') - span the timebin across "scan", "state", "field", or a combination of them (e.g., "scan,state") .. raw:: html </details> - polaverage_ (string='') - polarization averaging mode ("", "stokes" or "geometric"). - fitfunc_ (string='gaussian') - function for fitting ["gaussian", "lorentzian"] - fitmode_ (string='list') - mode for setting additional channel masks. "list" and "auto" are available now. .. raw:: html <details><summary><i> fitmode = list </i></summary> - nfit_ (intVec=[0]) - list of number of lines to fit in maskline region. .. raw:: html </details> .. raw:: html <details><summary><i> fitmode = auto </i></summary> - thresh_ (double=5.0) - S/N threshold for linefinder - avg_limit_ (int=4) - channel averaging for broad lines - minwidth_ (int=4) - the minimum channel width to detect as a line - edge_ (intVec=[0, 0]) - channels to drop at beginning and end of spectrum .. raw:: html </details> .. raw:: html <details><summary><i> fitmode = interact </i></summary> - nfit_ (intVec=[0]) - list of number of lines to fit in maskline region. .. raw:: html </details> - outfile_ (string='') - name of output file - overwrite_ (bool=False) - overwrite the output file if already exists [True, False] .. _Returns: Returns stats (dict) - line statistics including peak, center, FWHM, and number of lines, all with error estimates .. _Description: Description Task **sdfit** is a basic line fitter for single-dish spectra. While it's possible to run **sdfit** on uncalibrated data, the structure of the raw bandpass is likely to return complicated results that are difficult to parse meaningfully. It's therefore recommended to run **sdfit** on calibrated data. The task can fit Gaussian or Lorentzian functions. The masks for fitting (i.e. selection of the fitting ranges) can be computed automatically, or provided specifically by the user. .. note:: **NOTE**: Multiple scans, IFs, and polarizations can in principle be handled, but it is recommended to use *scan*, *field*, *spw*, and *pol* to give a single selection for each fit. The task produces a Python dictionary of line statistics as output, with keys: 'peak', 'cent', 'fwhm', and 'nfit'. See examples on referencing the keys, below. Configurable inputs enable control over data selection, averaging/binning behavior, specific handling of polarizations, fitting types, and restrictions and output control. Selection is by spectral window/channels, field IDs, and antennas through the *spw*, *field*, *pol, intent * and *antenna* selection parameters. Defaults are that all data are considered in fitting. Averaging can be computed over time intervals, with the *timebin* parameter. Leaving it unset (the default) indicates no time averaging. The *timespan* parameter determines which axes will be averaged, in terms of 'scan', 'state' or 'field'. So multiple scans or fields can be averaged together with this parameter. Two modes of polarization averaging are available via *polaverage*, though the difference is subtle; the options are "Stokes" (the default) and "Geometric". The differences manifest in the way the weightings are incorporated in the computation. "Stokes" mode computes Stokes I as: :math:`I = (XX + YY) / 2.` and the associated weight as: :math:`w_I = 4 / ( 1/w_{XX} + 1/w_{YY} )` "Geometric" mode implements the computation of Stokes I by folding in weights for XX and YY as follows: :math:`I = (XX * w_{XX} + YY * w_{YY}) / (w_{XX} + w_{YY})` And the associated weight as: :math:`w_I = w_{XX} + w_{YY}` "Geometric" mode is consistent with the historical implementation of computing Stokes I, though it is not formally correct since it assumes the weightings for XX and YY are equal, generally not the case. It is provided for users requiring backward compatibility. *fitmode* in **sdfit** enables fitting modes 'list' and 'auto' at this point. The 'list' mode allows users to set initial parameters (line region and number of lines per region) for the fit. In 'list' mode, users must give line region via the *spw* parameter by using MS selection syntax, while the number of lines per region can be specified via the *nfit* parameter. In 'auto' mode, the line finder detects channel ranges of spectral lines based on median absolute deviation (MAD) of the spectra using user defined criteria with the sub-parameters *thresh*, *avg_limit*, *minwidth*, and *edge*. The number of channels at both edges of spectra defined by the *edge* parameter are ignored in line detection. The median of the lower 80% of MAD values in a spectrum is multiplied by the *thresh* parameter value to define a threshold of line detection. All channels with MAD above the threshold are identified as spectral line candidates and accepted as spectral lines only if the channel width of the line exceeds the value of *minwidth* parameter. The line detection is iteratively invoked for channel-averaged spectra up to *avg_limit*. *thresh* -- [default 5] S/N threshold for linefinder. *avg_limit* -- [default 4] channel averaging for broad lines. A number of consecutive channels up to this value will be averaged to search for broad lines *minwidth* --[default: 4] minimum number of consecutive channels required to pass threshold *edge* -- [default 0] channels to drop at beginning and end of spectrum .. note:: **NOTE**: For bad baselines, *thresh* 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. Detailed output is directed to a log file identified by the '*outfile*' parameter. .. _Examples: Examples This example is to fit two Gaussian (default) components to all integrations in scan 4, polarization 'XX' only, and write the output to a file. The output (sdfitout) is a python dictionary. :: sdfitout = sdfit(infile=mymeasurement_set, datacolumn='data', scan='4', outfile='sdfit.log', overwrite=T, nfit=[2], pol='XX') An Example of output file: :: #SCAN TIME ANT BEAM SPW POL Function P0 P1 P2 4 4873839081.0780 2 0 6 0 gauss0 2.58050537 15.00975037 3.89437151 4 4873839081.0780 2 0 6 0 gauss1 0.72443587 61.37811279 8.87286472 In this example, only a spectrum is selected in an MS. Each row of the output file stores the results of fitting a line in the spectrum. The columns P0, P1, and P2, store the peak, channel index of line center, and full-width-half-maximum (FWHM, in channels), respectively. The task returns a dictionary of fit results which stores the number of lines, 'nfit', and the fit of each line, i.e., the line center, 'cent', the full-width-half-maximum, 'fwhm', and peak, 'peak'. Each value except for 'nfit' is a list of 2 entries [fit value, error]. :: sdfitout Out[1]: {'cent': [[[15.00975037, 0.04713312], [61.37811279, 0.25342196]]], 'fwhm': [[[3.89437151, 0.11099002], [8.87286472, 0.59676313]]], 'nfit': [2], 'peak': [[[2.58050537, 0.06369157], [0.72443587, 0.04219575]]]} To obtain the peak of the second line in the first spectrum from the dictionary, :: sdfitout['peak'][0][1] Out[2]: [0.72443587, 0.04219575] The first entry is the fitted value and the second one is the error on the fitted value. To fit three lines in a region: :: sdfitout = sdfit(infile=mymeasurement_set, fitmode='list', nfit=[3]) To fit two lines in two regions: :: sdfitout = sdfit(infile=mymeasurement_set, fitmode='list', nfit=[2,2]) To automatically fit any lines with S/N > 2, averaging over four channels (i.e. smoothing), and requiring lines to be at least 10 channels wide, while excluding channels 0:1000 from beginning and 500:end from the end of the spectrum: :: sdfitout = sdfit(infile=mymeasurement_set, fitmode='auto', edge=[1000,500], avg_limit='4', thresh='2', minwidth='10') This example directs the output to a file, mysd.fit : :: sdfitout = sdfit(infile=mymeasurement_set, outfile='mysd.fit') .. _Development: Development No additional development details .. _Details: Parameter Details Detailed descriptions of each function parameter .. _infile: | ``infile (path)`` - name of input SD dataset .. _datacolumn: | ``datacolumn (string='data')`` - name of data column to be used ["data", "float_data", or "corrected_data"] .. _antenna: | ``antenna (string='')`` - select data by antenna name or ID, e.g. "PM03" .. _field: | ``field (string='')`` - select data by field IDs and names, e.g. "3C2*" (""=all) .. _spw: | ``spw (string='')`` - select data by IF IDs (spectral windows), e.g. "3,5,7" (""=all) .. _timerange: | ``timerange (string='')`` - select data by time range, e.g. "09:14:0~09:54:0" (""=all) (see examples in help) .. _scan: | ``scan (string='')`` - select data by scan numbers, e.g. "21~23" (""=all) .. _pol: | ``pol (string='')`` - select data by polarization IDs, e.g. "XX,YY" (""=all) .. _intent: | ``intent (string='')`` - select data by observational intent, e.g. "*ON_SOURCE*" (""=all) .. _timebin: | ``timebin (string='')`` - bin width for time averaging .. _timespan: | ``timespan (string='')`` - span the timebin across "scan", "state", "field", or a combination of them (e.g., "scan,state") .. _polaverage: | ``polaverage (string='')`` - polarization averaging mode ("", "stokes" or "geometric"). .. _fitfunc: | ``fitfunc (string='gaussian')`` - function for fitting .. _fitmode: | ``fitmode (string='list')`` - mode for setting additional channel masks. .. _nfit: | ``nfit (intVec=[0])`` - list of number of lines to fit in maskline region. .. _thresh: | ``thresh (double=5.0)`` - S/N threshold for linefinder .. _avg_limit: | ``avg_limit (int=4)`` - channel averaging for broad lines .. _minwidth: | ``minwidth (int=4)`` - the minimum channel width to detect as a line .. _edge: | ``edge (intVec=[0, 0])`` - channels to drop at beginning and end of spectrum .. _outfile: | ``outfile (string='')`` - name of output file .. _overwrite: | ``overwrite (bool=False)`` - overwrite the output file if already exists """ pass