sdstat.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_sdstat
def sdstat(infile='', antenna=0, fluxunit='', telescopeparm='', specunit='', restfreq='', frame='', doppler='', scanlist=[], field='', iflist=[], pollist=[], masklist=[], invertmask=False, interactive=False, outfile='', format='3.3f', overwrite=False):

        """ASAP SD task: list statistics of spectral region
        Keyword arguments:
        infile -- name of input SD dataset
                default: none - must input file name
                example: 'mysd.asap'
                         See sdcal for allowed formats.
        antenna -- antenna name or id (only effective for MS input). 
        fluxunit -- units for line flux
                options: (str) '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)
            >>> specunit expandable parameter
                 restfreq -- rest frequency
                         default: '' (use current setting)
                         example: 4.6e10 (float value in Hz),
                                  '46GHz' (string with unit),
                                  ['345.8GHz', 347.0e9, 356.7e9] (for each IF)
                                  [{'name':'CO','value':345e9}] (a value with name)
        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
        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 field, scanlist, and pollist
        pollist -- list of polarization id numbers to select
                default: [] (use all pols)
                example: [1]
                this selection is in addition to field, scanlist, and iflist
        masklist -- list of mask regions to INCLUDE in stats
                default: [] (whole spectrum)
                example: [4000,4500] for one region
                         [[1000,3000],[5000,7000]]
                         these must be pairs of [lo,hi] boundaries
        invertmask -- invert mask (EXCLUDE masklist instead)
                options: (bool) True,False
                default: false
        interactive -- determines interactive masking
                options: (bool) True,False
                default: False
                example: interactive=True 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. 
        outfile -- name of output file for line statistics
                default: '' (no output statistics file)
                example: 'stat.txt'
        format -- format string to print statistic values
                default: '3.3f'
        overwrite -- overwrite the statistics file if already exists 
                options: (bool) True,False
                default: False

        -------------------------------------------------------------------
                Returns: a Python dictionary of line statistics
                   keys: 'rms','stddev','max','min','max_abscissa',
                         'min_abscissa','sum','median','mean','totint','eqw'
                example: xstat=sdstat(); print "rms = ",xstat['rms']
                         these can be used for testing in scripts or
                         for regression

                         'max_abscissa' and 'min_abscissa' refer to the abscissa
                         (channel/frequency/velocity) of max and min intensity.
                         'totint' is the integrated intensity (sum*dx)
                         where dx is the abscissa interval in 'specunit'.
                         'eqw' is equivalent width (totint/mag) where mag
                         is either max or min depending on which has
                         greater magnitude. 
                         Note that 'max_abscissa', 'min_abscissa', 'totint' 
                         and 'eqw' are quantities (python dictionaries with
                         keys, 'unit' and 'value').


       DESCRIPTION:

        Task sdstat computes basic statistics (rms,mean,median,sum)
        for single-dish spectra.  It assumes that the spectra have
        been calibrated.  Furthermore, it assumes that any
        time and channel averaging/smoothing has also already been done as
        there are no controls for these. 

        Note that multiple scans and IFs can in principle be handled, but
        we recommend that you use scanlist, field, iflist, and pollist to give 
        a single selection for each run.

        WARNING: If you do have multiple scantable rows, then the returning 
        values will be lists.

        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), and telescopeparm='',
        for the AT telescopes it will use internal telescope parameters for
        flux conversion. For GBT, it will use an approximate aperture
        efficiency conversion.  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.

        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(masklist)==int: masklist=[masklist]

#
#    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['scanlist'] = scanlist
        mytmp['field'] = field
        mytmp['iflist'] = iflist
        mytmp['pollist'] = pollist
        mytmp['masklist'] = masklist
        mytmp['invertmask'] = invertmask
        mytmp['interactive'] = interactive
        mytmp['outfile'] = outfile
        mytmp['format'] = format
        mytmp['overwrite'] = overwrite
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'sdstat.xml')

        casalog.origin('sdstat')
        if trec.has_key('sdstat') and casac.utils().verify(mytmp, trec['sdstat']) :
            result = task_sdstat.sdstat(infile, antenna, fluxunit, telescopeparm, specunit, restfreq, frame, doppler, scanlist, field, iflist, pollist, masklist, invertmask, interactive, outfile, format, overwrite)

        else :
          result = False
        return result