|
|||
NRAO Home > CASA > CASA Task Reference Manual |
|
0.1.103 sdcalold
Requires:
Synopsis
ASAP SD task [DEPRECATED]: calibration
Description
### DEPRECATION WARNING
#################################################
This task will be removed in CASA 5.1. To a very great extent, the
functionality of this task with MeasurementSet format is replicated with sdcal.
#########################################################################
Task sdcalold performs calibration for single-dish spectra. The parameter, calmode, defines calibration mode. The available calibration modes are ’ps’ (for position switching with explicit reference scans), ’otfraster’ (for raster OTF scan without explicit reference scans), ’otf’ (for non-raster OTF scan without explicit reference scans, e.g, Lissajous, double circle), ’fs’ (for frequency switching), ’nod’ (beam switching), and ’quotient’ (for position switching scans by ATNF telescopes). The task selects appropriate calbiration equation based on the value of calmode and telescope with which the data is taken. See below for details of calibration equation adopted in this task.
By setting calmode=’none’, one can run sdcalold on already calibrated data
for atmospheric optical depth correction.
Arguments
Inputs |
| ||
infile |
| name of input SD dataset
| |
| allowed: | string |
|
| Default: |
|
|
antenna |
| select an antenna name or ID, e.g, ’PM03’ (only effective
for MS input)
| |
| allowed: | any |
|
| Default: | variant 0 |
|
fluxunit |
| units of the flux (”=current)
| |
| allowed: | string |
|
| Default: |
|
|
telescopeparam |
| parameters of telescope for flux conversion (see examples
in help)
| |
| 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: |
| |
calmode |
| SD calibration mode
| |
| allowed: | string |
|
| Default: | ps |
|
fraction |
| fraction of the OFF data to mark as OFF spectra, e.g.,
’10%’
| |
| allowed: | any |
|
| Default: | variant 10% |
|
noff |
| number of the OFF data to mark (-1 = use fraction
instead of number)
| |
| allowed: | int |
|
| Default: | -1 |
|
width |
| width of the pixel for edge detection
| |
| allowed: | double |
|
| Default: | 0.5 |
|
elongated |
| the observed area is elongated in one direction
| |
| allowed: | bool |
|
| Default: | False |
|
markonly |
| do calibration (False) or just mark OFF (True)
| |
| allowed: | bool |
|
| Default: | False |
|
plotpointings |
| plot pointing direction for ON and OFF
| |
| allowed: | bool |
|
| Default: | False |
|
tau |
| the zenith atmospheric optical depth for correction (0.
= no correction)
| |
| allowed: | double |
|
| Default: | 0.0 |
|
verify |
| interactively verify the results of calibration [True, False]
(see description in help)
| |
| allowed: | bool |
|
| Default: | False |
|
outfile |
| name of output file (See a WARNING in help)
| |
| allowed: | string |
|
| Default: |
|
|
outform |
| output file format (See a WARNING in help)
| |
| allowed: | string |
|
| Default: | ASAP |
|
overwrite |
| overwrite the output file if already exists [True, False]
| |
| allowed: | bool |
|
| Default: | False |
|
plotlevel |
| plot and summarize results (0=none) see description in
help
| |
| allowed: | int |
|
| Default: | 0 |
|
void
Example
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.
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