NRAO Home > CASA > CASA Task Reference Manual

0.1.103 sdcal2old

Requires:

Synopsis
ASAP SD calibration task

Description

Task sdcal2old is an implementation of a calibration scheme like as interferometry, i.e., generate caltables and apply them. Available calibration modes are ’ps’, ’otf’, ’otfraster’, and ’tsys’. Those modes generates caltables for sky or Tsys calibration. Those caltables can be applied to the data by using calmode ’apply’.

The above three calibration modes, ’ps’, ’otf’, and ’otfraster’, generate sky calibration tables. 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) spectra ’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 spectra, ’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 spectra, 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 spectra. However, these modes should work even if explicit reference spectra exist. In this case, these spectra will be ignored and spectra 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 spectrum 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.



Arguments





Inputs

infile

name of input SD dataset (must be in scantable format)

allowed:

string

Default:

calmode

SD calibration mode

allowed:

string

Default:

ps

fraction

fraction of the OFF data to mark

allowed:

any

Default:

variant 10%

noff

number of the OFF data to mark

allowed:

int

Default:

-1

width

width of the pixel for edge detection

allowed:

double

Default:

0.5

elongated

whether observed area is elongated in one direction or not

allowed:

bool

Default:

False

tsysavg

Whether Tsys is averaged in spectral axis or not

allowed:

bool

Default:

False

tsysspw

list of IF IDs (spectral windows) and their channel ranges of averaging for Tsys calibration.

allowed:

string

Default:

applytable

(List of) sky and/or tsys tables

allowed:

any

Default:

variant

interp

Interpolation type in time[,freq]. Valid options are ”nearest”, ”linear”, ”cspline”, or any numeric string that indicates an order of polynomial interpolation. You can specify interpolation type for time and frequency separately by joining two of the above options by comma (e.g., ”linear,cspline”).

allowed:

string

Default:

spwmap

A dictionary indicating IFNO combinations to apply Tsys calibration to target. The key should be IFNO for Tsys calibration and its associated value must be a list of science IFNOs to be applied.

allowed:

any

Default:

variant

field

select data by field IDs and names, e.g. ’3C2*’ (” = all)

allowed:

string

Default:

spw

select data by IF IDs (spectral windows), e.g., ’3,5,7’ (” = all)

allowed:

string

Default:

scan

select data by scan numbers, e.g. ’21~23’ (”=all)

allowed:

string

Default:

pol

select data by polarization IDs, e.g, ’0,1’ (” = all)

allowed:

string

Default:

outfile

name of output file (See a WARNING in help)

allowed:

string

Default:

overwrite

overwrite the output file if already exists

allowed:

bool

Default:

False

Returns
void

Example

 
Keyword arguments:  
infile -- Name of input SD dataset  
calmode -- Calibration mode. If you want to generate calibration table  
           or apply existing calibration tables, set calmode to simple  
           string. On the other hand, if you want to calibrate data  
           on-the-fly, you have to set calmode to a composite calmode  
           string separated by comma. So far, sky calibration has three  
           types, ’ps’, ’otf’, and ’otfraster’. If observation is  
           configured to observe reference position, calmode must be  
           ’ps’. Otherwise, ’otf’ or ’otfraster’ should be used  
           depending on observing pattern. If observing pattern is  
           raster scan, calmode must be ’otfraster’ while ’otf’ must  
           be used when observing pattern is non-raster  
           (e.g., Lissajous).  
        options: ’ps’,’otf’,’otfraster’,’tsys’,’apply’  
        default: ’ps’  
        example: Here is an example for composite calmode.  
                 ’ps,apply’ (do sky cal and apply)  
                 ’ps,tsys,apply’ (do sky and Tsys cal and apply)  
    >>> 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 spectra 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 elongated  
                     in one direction.  
                default: False  
        tsysavg -- Whether Tsys is averaged in spectral axis or not.  
                default: False  
                options: (bool) True, False  
        tsysspw -- list of IF IDs (spectral windows) and their channel  
                   ranges of averaging for Tsys calibration.  
                   It does no effect if you don’t want to do Tsys  
                   calibration. the user is able to specify channel  
                   range for averaging (effective if tsysavg is True).  
                default: ’’ (auto-detect tsys spws)  
                example: tsysspw=’3,5,7’ (IF IDs 3,5,7; all channels)  
                         tsysspw=’<2’ (IF IDs less than 2; all channels)  
                         tsysspw=’1:0~100’ (IF ID1; between channels 0 and 100)  
        applytable -- List of sky/Tsys calibration tables you want to  
                      apply.  
                default: ’’  
        interp -- Interpolation method in time and frequency axis.  
                  Set comma separated method strings if you want  
                  to use different interpolation in time and  
                  frequency.  
                options: ’linear’, ’cspline’, ’nearest’,  
                         any numeric string indicating an order  
                         of polynomial.  
                default: ’’ (linear in time and frequency)  
                example: ’linear,cspline’ (linear in time, cubic  
                                           spline in frequency)  
                         ’linear,3’ (linear in time, third order  
                                     polynomial in frequency)  
                         ’nearest’ (nearest in time and frequency)  
        spwmap -- Dictionary defining transfer of Tsys calibration.  
                  Key must be IFNO for Tsys and its value must be  
                  a list of IFNOs for science target.  
                default: {}  
                example: {1: [5,6], 3: [7,8]}  
                         Tsys in IFNO1 is transferred to IFNO5, 6  
                         while Tsys in IFNO3 is to IFNO7, 8.  
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  
outfile -- Name of output file  
        NOTE if you omit, behavior of the task depends on calmode.  
        If calmode includes ’apply’, then omitting outfile indicates  
        that infile is overwritten by the calibrated data. In this case,  
        you have to set overwrite to True. If calmode doesn’t include  
        ’apply’, omitting outfile indicates that the task will use  
        default outfile name based on infile and predefined suffix  
        (’_sky’ for sky, ’_tsys’ for Tsys).  
        default: ’’ (<infile>_<suffix> for calibration  
                     while overwrite infile for apply mode)  
overwrite -- overwrite the output file if already exists  
        options: (bool) True,False  
        default: False  
        NOTE this parameter is ignored when outform=’ASCII’  
 
 
DESCRIPTION:  
 
Task sdcal2old is an implementation of a calibration scheme like as  
interferometry, i.e., generate caltables and apply them. Available  
calibration modes are ’ps’, ’otf’, ’otfraster’, and ’tsys’. Those  
modes generates caltables for sky or Tsys calibration. Those  
caltables can be applied to the data by using calmode ’apply’.  
 
The above three calibration modes, ’ps’, ’otf’, and ’otfraster’,  
generate sky calibration tables. 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) spectra  
    ’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 spectra, ’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 spectra, 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 spectra. However, these modes should work even if  
explicit reference spectra exist. In this case, these spectra  
will be ignored and spectra 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 spectrum 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.  
 
You can calibrate data on-the-fly like sdcal task by setting  
calmode to a composite calmode string separated by comma.  
For example, calmode=’ps,apply’ means doing sky calibration and  
apply it on-the-fly. In this case, caltable is generated as a  
temporary plain table and will be deleted at the end.  
Allowed calibration modes in this task is as follows:  
 
    ps  
        generate sky caltable using ’ps’ mode  
    otf  
        generate sky caltable using ’otf’ mode  
    otfraster  
        generate sky caltable using ’otfraster’ mode  
    tsys  
        generate tsys caltable  
    apply  
        apply caltables specified by applytable parameter  
    ps,apply  
        generate temporary sky caltable using ’ps’ mode and  
        apply it. also apply caltables specified by applytable  
    ps,tsys,apply  
        generate temporary sky caltable using ’ps’ mode as well  
        as temporary tsys caltable, and apply them.  
    otf,apply  
        generate temporary sky caltable using ’otf’ mode and  
        apply it. also apply caltables specified by applytable  
    otf,tsys,apply  
        generate temporary sky caltable using ’otf’ mode as well  
        as temporary tsys caltable, and apply them.  
    otfraster,apply  
        generate temporary sky caltable using ’otfraster’ mode  
        and apply it. also apply caltables specified by applytable  
    otfraster,tsys,apply  
        generate temporary sky caltable using ’otfraster’ mode  
        as well as temporary tsys caltable, and apply them.  
 
There are several control parameters for sky/Tsys calibration and  
application of caltables. See the above parameter description.  
 
In ALMA, Tsys measurement is usually done using different spectral  
setup from spectral windows for science target. In this case, sdcal2old  
transfers Tsys values to science spectral windows in the application  
stage. To do that, the user has to give a list of spectral windows for  
Tsys measurement as well as mapping between spectral windows for Tsys  
measurement and scicence target. These can be specified by parameters  
’tsysspw’ and ’spwmap’, which are defined as subparameters of ’calmode’.  
For example, suppose that Tsys measurements for science windows 17, 19,  
21, and 23 are done in spw 9, 11, 13, and 15, respectively.  
In this case, tsysspw and spwmap should be specified as follows:  
 
    tsysspw = ’9,11,13,15’  
    spwmap = {9:[17],11:[19],13:[21],15:[23]}  
 
Below is an example of full specification of task parameters for calmode  
of ’ps,tsys,apply’:  
 
    default(sdcal2old)  
    infile = ’foo.asap’  
    calmode = ’ps,tsys,apply’  
    spw = ’’  
    tsysspw = ’9,11,13,15’  
    spwmap = {9:[17],11:[19],13:[21],15:[23]}  
    outfile = ’bar.asap’  
    sdcal2old()  
 
Note that, in contrast to applycal task, spwmap must be a dictionary  
with Tsys spectral window as key and a list of corresponding science  
spectral window as value. Note also that the parameter ’spw’ should  
not be used to specify a list of spectral windows for Tsys measurement.  
It is intended to select data to be calibrated so that the list should  
contain spectral windows for both science target and Tsys measurement.  
The task will fail if you use ’spw’ instead of ’tsysspw’.  
 
For Tsys calibration, the user is able to choose whether Tsys is  
averaged in spectral axis or not. If tsysavg is False (default),  
resulting Tsys is spectral value. On the other hand, when tsysavg  
is True, Tsys is averaged in spectral axis before output. The channel  
range for averaging is whole channels by default. If channel range is  
specified by tsysspw string, it is used for averaging. The user can  
specify channel range with ms selection syntax. For example,  
 
    tsysspw = ’1:0~100’  
 
specifies spw 1 for Tsys calibration and channel range between channel  
0 and 100 for averaging. You can specify more than one ranges per spw.  
 
    tsysspw = ’1:0~100;200~400’  
 
In this case, selected ranges are between 0 and 100 plus 200 and 400.  
Note that even if multiple ranges are selected, the task average whole  
ranges together and output single averaged value. You can specify multiple  
spws by separating comma.  
 
    tsysspw = ’1:0~100,3:400~500’  
 
Note that specified channel range is ignored if tsysavg is False.  


More information about CASA may be found at the CASA web page

Copyright 2016 Associated Universities Inc., Washington, D.C.

This code is available under the terms of the GNU General Public Lincense


Home | Contact Us | Directories | Site Map | Help | Privacy Policy | Search