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)  
       NOTE this task only supports IF ID selction and ignores channel  
       selection.  
        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)  
        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  
 
calmode -- calibration mode  
        options: ’ps’,’nod’,’otf’,’otfraster’,  
                 ’fs’,’quotient’,’none’  
        default: ’ps’  
        example: choose mode ’none’ if you have  
                 already calibrated and want to  
                 correct for atmospheric opacity defined by tau.  
    >>> calmode expandable parameter  
         fraction -- edge marker parameter of ’otf’ and ’otfraster’.  
                     Specify a number of OFF integrations (at each  
                     side of the raster rows in ’otfraster’ mode)  
                     as a fraction of total number of integrations.  
                     In ’otfraster’ mode, number of integrations  
                     to be marked as OFF, n_off, is determined by  
                     the following formula,  
 
                        n_off = floor(fraction * n),  
 
                     where n is number of integrations per raster  
                     row. Note that n_off from both sides will be  
                     marked as OFF so that twice of specified  
                     fraction will be marked at most. For example,  
                     if you specify fraction=’10%’, resultant  
                     fraction of OFF integrations will be 20% at  
                     most.  
                     In ’otf’ mode, n_off is given by,  
 
                        n_off = floor(fraction * n),  
 
                     where n is number of total integrations.  
                     n_off is used as criterion of iterative marking  
                     process. Therefore, resulting total number of  
                     OFFs will be larger than n_off. In practice,  
                     fraction is a geometrical fraction of edge  
                     region. Thus, if integrations are concentrated  
                     on edge region (e.g. some of Lissajous  
                     patterns), then resulting n_off may be  
                     unexpectedly large.  
                 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. Note that n_off from both sides will  
                 be marked as OFF so that twice of specified noff  
                 will be marked at most.  
                 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.  
                 options: (bool) True, False  
                 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.  
                 options: (bool) True, False  
                 default: False  
         plotpointings -- load plotter and plot pointing directions of  
                          ON and OFF scans.  
                 options: (bool) True, False  
                 default: False  
 
tau -- the zenith atmospheric optical depth for correction  
        default: 0.0 (no correction)  
verify -- interactively verify the results of calibration.  
          When verify = True, for the first six on-source spectra (at  
          max), spectra before and after the calibration are displayed  
          in a plot window. At the prompt there are two choices of  
          action: ’Y’ (accept the operation for whole dataset),  
          ’N’ (reject the operation and finish task).  
          Note that when the operation is rejected by ’N’,  
          no operation is done to the spectrum/spectra.  
        options: (bool) True,False  
        default: False  
outfile -- name of output file  
        default: ’’ (<infile>_cal)  
outform -- output file format  
        options: ’ASAP’,’MS2’, ’ASCII’,’SDFITS’  
        default: ’ASAP’  
        NOTE the ASAP format is easiest for further sd  
        processing; use MS2 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  
        NOTE this parameter is ignored when outform=’ASCII’  
plotlevel -- control for plotting of results  
        options: (int) 0, 1, 2, and their negative counterparts  
        default: 0 (no plotting)  
        example: plotlevel=1; plot calibrated spectra  
                 plotlevel=2; additionally list data before and after operation.  
                 plotlevel<0 as abs(plotlevel), e.g.  
                 -1 => hardcopy of final plot (will be named  
                 <outfile>_calspec.eps)  
 
 
DESCRIPTION:  
 
---------------------  
HOW TO CHOOSE CALMODE  
---------------------  
For position switching calibration, the user should choose appropriate  
calibration mode depending on the data. Use case for each mode is as  
follows:  
 
    ’ps’: position switch (including OTF) with explicit reference (OFF)  
          scans  
    ’otf’: non-raster OTF scan without explicit OFFs (e.g. Lissajous,  
           double circle, etc.) intends to calibrate fast scan data  
    ’otfraster’: raster OTF scan without explicit OFFs  
 
So, if the data contains explicit reference scans, ’ps’ should be used.  
Otherwise, ’otfraster’ and ’otf’ are appropriate for raster OTF and  
non-raster OTF, respectively. In ’otf’ and ’otfraster’ modes, the task  
first try to find several integrations  near edge as OFF scans, then the  
data are calibrated using those OFFs. If the observing pattern is raster,  
you should use the ’otfraster’ mode to calibrate data. Otherwise, the  
’otf’ mode should be used. For detail about edge marking, see inline help  
of sd.edgemarker module and its methods.  
Those modes are designed for OTF observations without explicit OFF scans.  
However, these modes should work even if explicit reference scans exist.  
In this case, explicit reference scans will be ignored and scans near  
edges detected by edge marker will be used as reference.  
 
Except for how to choose OFFs, the procedure to derive calibrated  
spectra is common for the above three modes. Selected (or preset) OFF  
integrations are separated by its continuity in time domain, averaged  
in each segment, then interpolated to timestamps for ON integrations.  
Effectively, it means that OFF integrations are averaged by each OFF  
scans for ’ps’ mode, averaged by either ends of each raster row for  
’otfraster’ mode, averaged by each temporal segments of detected edges  
for ’otf’ mode. The formula for calibrated spectrum is  
 
    Tsys * (ON - OFF) / OFF.  
 
The ’fs’ mode is for frequency switch calibration. Currently, only GBT  
frequency switch data is supported.  
 
The ’quotient’ mode is special mode for "AT" telescopes, namely ANNF  
MOPRA. It assumes that observing sequence looks like "target, reference,  
target, reference,..." and it derives calibrated spectrum by applying  
the above formula to the pair of "target" and "reference" in order.  
Reference spectra are not averaged in this mode.  
 
 
--------------------  
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 sdcalold 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.  
 
-------  
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.