sdreduce.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_sdreduce
def sdreduce(infile='', antenna=0, fluxunit='', telescopeparm='', specunit='', restfreq='', frame='', doppler='', calmode='none', fraction='10%', noff=-1, width=0.5, elongated=False, markonly=False, plotpointings=False, scanlist=[], field='', iflist=[], pollist=[], channelrange=[], average=False, scanaverage=False, timeaverage=False, tweight='none', averageall=False, polaverage=False, pweight='none', tau=0.0, kernel='none', kwidth=5, chanwidth='5', masklist=[], maskmode='auto', thresh=5.0, avg_limit=4, edge=[0], blfunc='none', order=5, npiece=2, applyfft=True, fftmethod='fft', fftthresh=3.0, addwn=[], rejwn=[], clipthresh=3.0, clipniter=0, verifycal=False, verifysm=False, verifybl=False, verbosebl=True, bloutput=True, blformat='', showprogress=True, minnrow=1000, outfile='', outform='ASAP', overwrite=False, plotlevel=0):

        """ASAP SD task: do sdcal, sdsmooth, and sdbaseline in one task
  Keyword arguments:
        infile -- name of input SD dataset
        antenna -- antenna name or id (only effective for MS input). 
        fluxunit -- units for line flux
                options: 'K','Jy',''
                default: '' (keep current fluxunit)
                WARNING: For GBT data, see description below.
            >>> fluxunit expandable parameter
                 telescopeparm -- the telescope characteristics
                        options: (str) name or (list) list of gain info
                        default: '' (none set)
                        example: if telescopeparm='', 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.
                                 telescopeparm=[104.9,0.43] diameter(m), ap.eff.
                                 telescopeparm=[0.743] gain in Jy/K
                                 telescopeparm='FIX' to change default fluxunit
                                 see description below

        specunit -- units for spectral axis
                options: (str) 'channel','km/s','GHz','MHz','kHz','Hz',''
                default: '' (=current)
                example: this will be the units for masklist
            >>> specunit expandable parameters
                 restfreq -- 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 nIF. dictionary 
                         input should be a pair of molecule name and frequency with 
                         keys of 'name' and 'value', respectively. values in the 
                         dictionary input follows the same manner 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 frame for spectral axis
                options: (str) 'LSRK','REST','TOPO','LSRD','BARY',
                         'GEO','GALACTO','LGROUP','CMB'
                default: currently set frame in scantable
                WARNING: frame='REST' not yet implemented
        doppler -- doppler mode
                options: (str) 'RADIO','OPTICAL','Z','BETA','GAMMA'
                default: currently set doppler in scantable
        calmode -- calibration mode
                options: 'ps','nod','fs','fsotf','quotient','none'
                default: 'none'
                example: choose mode 'none' if you have
                         already calibrated and want to
                         try baselines or averaging
            >>> calmode expandable parameter
                 fraction -- Edge marking parameter for 'otf' and 'otfraster'.
                             specify a number of OFF scans as a fraction of 
                             total number of data points. 
                         default: '10%'
                         options: '20%' in string style or float value less 
                                  than 1.0 (e.g. 0.15).
                                  'auto' is available only for 'otfraster'. 
                 noff -- Edge marking parameter for 'otfraster'.
                         It is used to specify a number of OFF scans near 
                         edge directly. Value of noff comes before setting 
                         by fraction.
                         default: -1 (use fraction)
                         options: any positive integer
                 width -- Edge marking parameter for 'otf'.
                          Pixel width with respect to a median spatial 
                          separation between neighboring two data in time.
                          Default will be fine in most cases.
                         default: 0.5
                         options: float value
                 elongated -- Edge marking parameter for 'otf'.
                              Set True only if observed area is elongeted 
                              in one direction.
                         default: False
                 markonly -- Set True if you want to save data just after 
                             edge marking (i.e. uncalibrated data) to see 
                             how OFF scans are defined.
                         default: False
        scanlist -- list of scan numbers to process
                default: [] (use all scans)
                example: [21,22,23,24]
                this selection is in addition to field, iflist, and pollist
        field -- selection string for selecting scans by name
                default: '' (no name selection)
                example: 'FLS3a*'
                this selection is in addition to scanlist, iflist, and pollist
        iflist -- list of IF id numbers to select
                default: [] (use all IFs)
                example: [15]
                this selection is in addition to scanlist, field, and pollist
        pollist -- list of polarization id numbers to select
                default: [] (use all polarizations)
                example: [1]
                this selection is in addition to scanlist, field, and iflist
        channelrange -- channel range selection
                default: [] (use all channel)
                example: [0,5000]
                Note that specified values are recognized as 'channel' 
                regardless of the value of specunit 
        average -- averaging on spectral data 
                options: (bool) True,False
                default: False

            >>>average expandable parameter
                 scanaverage -- average integrations within scans
                         options: (bool) True,False
                         default: False
                         example: if True, this happens in read-in
                         For GBT, set False!
                 timeaverage -- average times for multiple scan cycles
                         options: (bool) True,False
                         default: False
                         example: if True, this happens after calibration
                 tweight -- weighting for time average
                         options: 'none'
                                  'var'   (1/var(spec) weighted)
                                  'tsys'  (1/Tsys**2 weighted)
                                  'tint'  (integration time weighted)
                                  'tintsys'  (Tint/Tsys**2)
                                  'median'  ( median averaging)
                         default: 'none'
                 averageall -- average multi-resolution spectra
                               spectra are averaged by referring 
                               their frequency coverage
                         default: False
                 polaverage -- average polarizations
                         options: (bool) True,False
                         default: False
                 pweight -- weighting for polarization average
                         options: 'none'
                                  'var'  (1/var(spec) weighted)
                                  'tsys' (1/Tsys**2 weighted)

        tau -- atmospheric optical depth
                default: 0.0 (no correction)
        kernel -- type of spectral smoothing
                options: 'none','hanning','gaussian','boxcar','regrid'
                default: 'none' (no smoothing)

            >>>kernel expandable parameter
                 kwidth -- width of spectral smoothing kernel
                         options: (int) in channels
                         default: 5
                         example: 5 or 10 seem to be popular for boxcar
                                  ignored for hanning (fixed at 5 chans)
                                  (0 will turn off gaussian or boxcar)
                 chanwidth -- channel width of regridded spectra
                         default: '5' (in channels)
                         example: '500MHz', '0.2km/s'
        masklist -- list or string of mask regions to INCLUDE in BASELINE fit
                    a string masklist allows per IF selection of channels.
                default: [] (entire spectrum)
                example: [[1000,3000],[5000,7000]]
                         '0:1000~3000;5000~7000, 1:200~350;450~600'
                         when maskmode is 'auto' or 'interact', this mask 
                         will be applied first before fitting as base mask
        maskmode -- mode of setting additional channel masks for baselining
                options: (str) 'auto','list','interact'
                default: 'auto'
                example: maskmode='auto' runs linefinder to detect line regions 
                         to be excluded from fitting. this mode requires three 
                         expandable parameters: thresh, avg_limit, and edge.
                         USE WITH CARE! May need to tweak the expandable parameters.
                         maskmode='list' uses the given masklist only: 
                         no additional masks applied.
                         maskmode='interact' allows users to manually modify the 
                         mask regions by dragging mouse on the spectrum plotter GUI.
                         use LEFT or RIGHT button to add or delete regions, 
                         respectively.

            >>> maskmode expandable parameters
                 thresh -- S/N threshold for linefinder
                         default: 5
                         example: a single channel S/N ratio above which the channel is
                                  considered to be a detection
                 avg_limit -- channel averaging for broad lines
                         default: 4
                         example: a number of consecutive channels not greater than
                                  this parameter can be averaged to search for broad lines
                 edge -- channels to drop at beginning and end of spectrum
                         default: 0
                         example: [1000] drops 1000 channels at beginning AND end
                                  [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.

        blfunc -- baseline model function
                options: (str) 'none','poly','chebyshev','cspline','sinusoid'
                default: 'none' (no baselining)
                example: blfunc='poly' uses a single polynomial line of 
                         any order which should be given as an expandable 
                         parameter 'order' to fit baseline. 
                         blfunc='chebyshev' uses Chebyshev polynomials. 
                         blfunc='cspline' uses a cubic spline function, a piecewise 
                         cubic polynomial having C2-continuity (i.e., the second 
                         derivative is continuous at the joining points).
                         blfunc='sinusoid' uses a combination of sinusoidal curves. 
            >>> blfunc expandable parameters
                 order -- order of baseline polynomial
                         options: (int) (<0 turns off baseline fitting)
                         default: 5
                         example: typically in range 2-9 (higher values
                                  seem to be needed for GBT)
                 npiece -- number of the element polynomials of cubic spline curve
                         options: (int) (<0 turns off baseline fitting)
                         default: 2
                 applyfft -- automatically set wave numbers of sinusoidal functions
                         for fitting by applying some method like FFT.
                         options: (bool) True, False
                         default: True
                 fftmethod -- method to be used when applyfft=True. Now only
                         'fft' is available and it is the default.
                 fftthresh -- threshold to select wave numbers to be used for
                         sinusoidal fitting. both (float) and (str) accepted.
                         given a float value, the unit is set to sigma.
                         for string values, allowed formats include:
                             'xsigma' or 'x' (= x-sigma level. e.g., '3sigma'), or
                             'topx' (= the x strongest ones, e.g. 'top5').
                         default is 3.0 (unit: sigma).
                 addwn -- additional wave number(s) of sinusoids to be used
                         for fitting.
                         (list) and (int) are accepted to specify every
                         wave numbers. also (str) can be used in case
                         you need to specify wave numbers in a certain range,
                         e.g., 'a-b' (= a, a+1, a+2, ..., b-1, b),
                               '<a'  (= 0,1,...,a-2,a-1),
                               '>=a' (= a, a+1, ... up to the maximum wave
                                      number corresponding to the Nyquist
                                      frequency for the case of FFT).
                         default: []
                 rejwn -- wave number(s) of sinusoid NOT to be used for fitting.
                         can be set just as addwn but has higher priority:
                         wave numbers which are specified both in addwn
                         and rejwn will NOT be used.
                         default: []
                 clipthresh -- clipping threshold for iterative fitting
                         default: 3
                 clipniter -- maximum iteration number
                         default: 0 (no iteration, i.e., no clipping)

        verifycal -- verify the results of calibration
                options: (bool) True,False
                default: False
                WARNING: Currently verifying parameters just asks whether you 
                         accept the displayed calibraion/fit and if not, 
                         continues without doing any calibraion/baseline fit.
        verifysm -- verify the results of smoothing
                options: (bool) True,False
                default: False
                Note: verification is not yet available for kernel='regrid'
        verifybl -- verify the results of baseline fitting
                options: (bool) True,False
                default: False
                NOTE: Currently available only when blfunc='poly'
        verbosebl -- output fitting results to logger
                default: True
                example: If False, the fitting results including coefficients, 
                         residual rms, etc., are not output to the CASA logger, 
                         while the processing speed gets faster
        bloutput -- output fitting results to a text file
                default: True
                example: If False, the fitting results including coefficients, 
                         residual rms, etc., are not output to a text file 
                         (<outfile>_blparam.txt), while the processing 
                         speed gets faster
        blformat -- format of the logger output and text file specified with bloutput
                options: '', 'csv'
                default: '' (same as in the past, easy to read but huge)
        showprogress -- show progress status for large data
                default: True
        minnrow -- minimum number of input spectra to show progress status
                default: 1000
        outfile -- Name of output file
                default: '' (<infile>_cal)
        outform -- format of output file
                options: 'ASCII','SDFITS','MS','ASAP'
                default: 'ASAP'
                example: the ASAP format is easiest for further sd
                         processing; use MS for CASA imaging.
                         If ASCII, then will append some stuff to
                         the outfile name
        overwrite -- overwrite the output file if already exists
                options: (bool) True,False
                default: False
                WARNING: if outform='ASCII', this parameter is ignored
        plotlevel -- control for plotting of results
                options: (int) 0=none, 1=some, 2=more, <0=hardcopy
                default: 0 (no plotting)
                example: plotlevel<0 as abs(plotlevel), e.g.
                         -1 => hardcopy of final plot (will be named
                         <outfile>_calspec.eps)
                WARNING: be careful plotting in fsotf mode!


        DESCRIPTION:

        Task sdreduce performs data selection, calibration, and/or spectral
        baseline fitting for single-dish spectra. This task internally calls the
        tasks, sdcal, sdsmooth, and sdbaseline and it can be used to run all the
        three steps in one task execution.
        By setting calmode='none', one can run sdreduce on already calibrated data,
        for further selection, averaging and atmospheric optical depth correction.
        To save the output spectra in a certain range of channels, you set the 
        range in channelrange.

        If you give multiple IFs in iflist, then your scantable will have
        multiple IFs by default. Averaging of multi-resolution (multi-IFs)
        spectra can be achieved by setting a sub-parameter of average, 
        averageall, to True. It handles multi-IFs by selecting overlaps in 
        frequency coverages and assigning new IFs in the output spectra.

        ASAP recognizes the data of the "AT" telescopes, but currently
        does not know about the GBT or any other telescope. This task
        does know about GBT. Telescope name is obtained from the data.
        If you wish to change the fluxunit (see below), by leaving
        the sub-parameter telescopeparm unset (telescopeparm=''),
        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.
        If you give telescopeparm a list, then if the list has a single float it
        is assumed to be the gain in Jy/K, if two or more elements they are assumed
        to be telescope diameter (m) and aperture efficiency
        respectively.

        Note that sdreduce assumes that the fluxunit is set correctly in
        the data already.  If not, then set telescopeparm='FIX' and it
        will set the default units to fluxunit without conversion.
        NOTE: If the data in infile is an ms from GBT and the default flux
        unit is missing and this task automatically fixes the default fluxunit
        to 'K' before the conversion.

        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.  

  
        """
        if type(scanlist)==int: scanlist=[scanlist]
        if type(iflist)==int: iflist=[iflist]
        if type(pollist)==int: pollist=[pollist]
        if type(channelrange)==int: channelrange=[channelrange]
        if type(edge)==int: edge=[edge]

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

        mytmp['infile'] = infile
        mytmp['antenna'] = antenna
        mytmp['fluxunit'] = fluxunit
        mytmp['telescopeparm'] = telescopeparm
        mytmp['specunit'] = specunit
        mytmp['restfreq'] = restfreq
        mytmp['frame'] = frame
        mytmp['doppler'] = doppler
        mytmp['calmode'] = calmode
        mytmp['fraction'] = fraction
        mytmp['noff'] = noff
        mytmp['width'] = width
        mytmp['elongated'] = elongated
        mytmp['markonly'] = markonly
        mytmp['plotpointings'] = plotpointings
        mytmp['scanlist'] = scanlist
        mytmp['field'] = field
        mytmp['iflist'] = iflist
        mytmp['pollist'] = pollist
        mytmp['channelrange'] = channelrange
        mytmp['average'] = average
        mytmp['scanaverage'] = scanaverage
        mytmp['timeaverage'] = timeaverage
        mytmp['tweight'] = tweight
        mytmp['averageall'] = averageall
        mytmp['polaverage'] = polaverage
        mytmp['pweight'] = pweight
        mytmp['tau'] = tau
        mytmp['kernel'] = kernel
        mytmp['kwidth'] = kwidth
        mytmp['chanwidth'] = chanwidth
        mytmp['masklist'] = masklist
        mytmp['maskmode'] = maskmode
        mytmp['thresh'] = thresh
        mytmp['avg_limit'] = avg_limit
        mytmp['edge'] = edge
        mytmp['blfunc'] = blfunc
        mytmp['order'] = order
        mytmp['npiece'] = npiece
        mytmp['applyfft'] = applyfft
        mytmp['fftmethod'] = fftmethod
        mytmp['fftthresh'] = fftthresh
        mytmp['addwn'] = addwn
        mytmp['rejwn'] = rejwn
        mytmp['clipthresh'] = clipthresh
        mytmp['clipniter'] = clipniter
        mytmp['verifycal'] = verifycal
        mytmp['verifysm'] = verifysm
        mytmp['verifybl'] = verifybl
        mytmp['verbosebl'] = verbosebl
        mytmp['bloutput'] = bloutput
        mytmp['blformat'] = blformat
        mytmp['showprogress'] = showprogress
        mytmp['minnrow'] = minnrow
        mytmp['outfile'] = outfile
        mytmp['outform'] = outform
        mytmp['overwrite'] = overwrite
        mytmp['plotlevel'] = plotlevel
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'sdreduce.xml')

        casalog.origin('sdreduce')
        if trec.has_key('sdreduce') and casac.utils().verify(mytmp, trec['sdreduce']) :
            result = task_sdreduce.sdreduce(infile, antenna, fluxunit, telescopeparm, specunit, restfreq, frame, doppler, calmode, fraction, noff, width, elongated, markonly, plotpointings, scanlist, field, iflist, pollist, channelrange, average, scanaverage, timeaverage, tweight, averageall, polaverage, pweight, tau, kernel, kwidth, chanwidth, masklist, maskmode, thresh, avg_limit, edge, blfunc, order, npiece, applyfft, fftmethod, fftthresh, addwn, rejwn, clipthresh, clipniter, verifycal, verifysm, verifybl, verbosebl, bloutput, blformat, showprogress, minnrow, outfile, outform, overwrite, plotlevel)

        else :
          result = False
        return result