------------------------  
How to use return values  
------------------------  
xstat = sdstatold();  
print "rms = ",xstat[’rms’]  
 
these can be used for testing in scripts or for regression  
 
’max_abscissa’ and ’min_abscissa’ refer to the channel of max and min  
intensity.  
’totint’ is the integrated intensity (sum*channel).  
’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’).  
 
-------------------------------------  
AVERAGING OF SPECTRA  
-------------------------------------  
Task sdstatold 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.  
 
--------------------  
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 xxx 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.  
 
------------------  
Keyword arguments  
------------------  
infile -- name of input SD dataset  
        default: none - must input file name  
        example: ’mysd.asap’  
                 See sdcal for allowed formats.  
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)  
                 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)  
timerange -- select data by time range  
        default: ’’ (use all)  
        example: timerange = ’YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss’  
                 Note: YYYY/MM/DD can be dropped as needed:  
                 timerange=’09:14:00~09:54:00’ # this time range  
                 timerange=’09:44:00’ # data within one integration of time  
                 timerange=’>10:24:00’ # data after this time  
                 timerange=’09:44:00+00:13:00’ #data 13 minutes after time  
        this selection is in addition to the other selections to 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  
beam -- select data by beam IDs  
        default: ’’ (use all beams)  
        example: beam=’0,1’ (beam IDs 0,1)  
        this selection is in addition to the other selections to data  
timeaverage -- average spectra over time  
        options: (bool) True, False  
        default: False  
    >>> timeaverage expandable parameter  
        tweight -- weighting for time averaging  
                options: ’var’   (1/var(spec) weighted)  
                         ’tsys’  (1/Tsys**2 weighted)  
                         ’tint’  (integration time weighted)  
                         ’tintsys’  (Tint/Tsys**2)  
                         ’median’  ( median averaging)  
                default: ’tintsys’  
        scanaverage -- average spectra within a scan number  
                       when True, spectra are NOT averaged over  
                       different scan numbers.  
                options: (bool) True, False  
                default: False  
polaverage -- average spectra over polarizations  
        options: (bool) True, False  
        default: False  
    >>> polaverage expandable parameter  
        pweight -- weighting for polarization averaging  
                options: ’var’  (1/var(spec) weighted)  
                         ’tsys’ (1/Tsys**2 weighted)  
                default: ’tsys’  
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 (ASCII) to save 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’  
 
 
-------  
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.