|
|||
NRAO Home > CASA > CASA Task Reference Manual |
|
0.1.101 sdbaselineold
Requires:
Synopsis
ASAP SD task [DEPRECATED]: Fit/subtract a spectral baseline
Description
### DEPRECATION WARNING
#################################################
This task will be removed in CASA 5.1. The functionality of this task with
MeasurementSet format is replicated with sdbaseline.
#########################################################################
Task sdbaselineold performs baseline fitting/removal for single-dish spectra.
The fit parameters, terms and rms of base-line are saved to an ascii file,
’¡outfile¿_blparam.txt’.
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: |
|
|
restfreq |
| the rest frequency, e.g. ’1.41GHz’ (default unit: Hz) (see
examples in help)
| |
| allowed: | any |
|
| Default: | variant
|
|
frame |
| frequency reference frame (”=current)
| |
| allowed: | string |
|
| Default: |
|
|
doppler |
| doppler convention (”=current). Effective only when
spw selection is in velocity unit.
| |
| allowed: | string |
|
| Default: |
|
|
timerange |
| select data by time range, e.g. ’09:14:0~09:54:0’ (”=all)
(see examples in help)
| |
| 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: |
| |
tau |
| the zenith atmospheric optical depth for correction
| |
| allowed: | double | |
| Default: | 0.0 |
|
maskmode |
| mode of setting additional channel masks
| |
| allowed: | string |
|
| Default: |
|
|
thresh |
| S/N threshold for linefinder
| |
| allowed: | double | |
| Default: | 5.0 |
|
avg_limit |
| channel averaging for broad lines
| |
| allowed: | int | |
| Default: | 4 |
|
edge |
| channels to drop at beginning and end of spectrum
| |
| allowed: | intArray |
|
| Default: | 0 |
|
blfunc |
| baseline model function
| |
| allowed: | string |
|
| Default: | poly |
|
order |
| order of baseline model function
| |
| allowed: | int |
|
| Default: | 5 |
|
npiece |
| number of element polynomials for cubic spline curve
| |
| allowed: | int |
|
| Default: | 2 |
|
applyfft |
| automatically set wave numbers of sinusoids
| |
| allowed: | bool |
|
| Default: | True |
|
fftmethod |
| method for automatically set wave numbers of sinusoids
| |
| allowed: | string |
|
| Default: | fft |
|
fftthresh |
| threshold to select wave numbers of sinusoids
| |
| allowed: | any |
|
| Default: | 3.0 |
|
addwn |
| additional wave numbers to use
| |
| allowed: | any |
|
| Default: | 0 |
|
rejwn |
| wave numbers NOT to use
| |
| allowed: | any |
|
| Default: |
|
|
clipthresh |
| clipping threshold for iterative fitting
| |
| allowed: | double |
|
| Default: | 3.0 |
|
clipniter |
| maximum iteration number for iterative fitting
| |
| allowed: | int |
|
| Default: | 0 |
|
verify |
| interactively verify the results of operation for each
spectrum (see description in help)
| |
| allowed: | bool |
|
| Default: | False |
|
verbose |
| output fitting results to logger
| |
| allowed: | bool |
|
| Default: | True |
|
bloutput |
| output fitting results to a text file
| |
| allowed: | bool |
|
| Default: | True |
|
blformat |
| format of the text file specified with bloutput
| |
| allowed: | string |
|
| Default: |
|
|
showprogress |
| show progress status for large data
| |
| allowed: | bool |
|
| Default: | True |
|
minnrow |
| minimum number of input spectra to show progress
status
| |
| allowed: | int |
|
| Default: | 1000 |
|
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
| |
| allowed: | bool |
|
| Default: | False |
|
plotlevel |
| control for plotting of results (see examples 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)/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; all channels)
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
tau -- the zenith atmospheric optical depth for correction
default: 0.0 (no correction)
maskmode -- mode of setting additional channel masks
options: ’auto’, ’list’, or ’interact’
default: ’auto’
example: maskmode=’auto’ runs linefinder to detect line regions
to be excluded from fitting. this mode requires three
expandable parameters: thresh, avg_limit, and edge.
USE WITH CARE! May need to tweak the expandable parameters.
maskmode=’list’ uses the given masklist only: no additional
masks applied.
maskmode=’interact’ allows users to manually modify the
mask regions by dragging mouse on the spectrum plotter GUI.
use LEFT or RIGHT button to add or delete regions,
respectively.
>>> maskmode expandable parameters
thresh -- S/N threshold for linefinder. a single channel S/N ratio
above which the channel is considered to be a detection.
default: 5
avg_limit -- channel averaging for broad lines. a number of
consecutive channels not greater than this parameter
can be averaged to search for broad lines.
default: 4
edge -- channels to drop at beginning and end of spectrum
default: 0
example: edge=[1000] drops 1000 channels at beginning AND end.
edge=[1000,500] drops 1000 from beginning and 500
from end.
Note: For bad baselines threshold should be increased,
and avg_limit decreased (or even switched off completely by
setting this parameter to 1) to avoid detecting baseline
undulations instead of real lines.
blfunc -- baseline model function
options: ’poly’, ’chebyshev’, ’cspline’, or ’sinusoid’
default: ’poly’
example: blfunc=’poly’ uses a single polynomial line of
any order which should be given as an expandable
parameter ’order’ to fit baseline.
blfunc=’chebyshev’ uses Chebyshev polynomials.
blfunc=’cspline’ uses a cubic spline function, a piecewise
cubic polynomial having C2-continuity (i.e., the second
derivative is continuous at the joining points).
blfunc=’sinusoid’ uses a combination of sinusoidal curves.
>>> blfunc expandable parameters
order -- order of baseline model function
options: (int) (<0 turns off baseline fitting)
default: 5
example: typically in range 2-9 (higher values
seem to be needed for GBT)
npiece -- number of the element polynomials of cubic spline curve
options: (int) (<0 turns off baseline fitting)
default: 2
applyfft -- automatically set wave numbers of sinusoidal functions
for fitting by applying some method like FFT.
options: (bool) True, False
default: True
fftmethod -- method to be used when applyfft=True. Now only
’fft’ is available and it is the default.
fftthresh -- threshold to select wave numbers to be used for
sinusoidal fitting. both (float) and (str) accepted.
given a float value, the unit is set to sigma.
for string values, allowed formats include:
’xsigma’ or ’x’ (= x-sigma level. e.g., ’3sigma’), or
’topx’ (= the x strongest ones, e.g. ’top5’).
default is 3.0 (unit: sigma).
addwn -- additional wave number(s) of sinusoids to be used
for fitting.
(list) and (int) are accepted to specify every
wave numbers. also (str) can be used in case
you need to specify wave numbers in a certain range.
default: [0] (i.e., constant is subtracted at least)
example: 0
[0,1,2]
’a-b’ (= a, a+1, a+2, ..., b-1, b),
’<a’ (= 0,1,...,a-2,a-1),
’>=a’ (= a, a+1, ... up to the maximum wave
number corresponding to the Nyquist
frequency for the case of FFT).
rejwn -- wave number(s) of sinusoid NOT to be used for fitting.
can be set just as addwn but has higher priority:
wave numbers which are specified both in addwn
and rejwn will NOT be used.
default: []
clipthresh -- clipping threshold for iterative fitting
default: 3
clipniter -- maximum iteration number for iterative fitting
default: 0 (no iteration, i.e., no clipping)
verify -- interactively verify the results of operation for each spectrum.
When verify = True, for each input spectrum, spectra
before and after the operation are displayed in a plot
window. At the prompt there are four choices of action:
’Y’ (accept the operation and continue to the next input
spectrum), ’N’ (reject the operation and continue to the
next input spectrum), ’A’ (accept the current operation
and continue non-interactively), and ’R’ (reject the
current operation and exit from operation).
Note that when the operation is rejected by ’N’ or ’R’,
no operation is done to the spectrum/spectra.
options: (bool) True,False
default: False
NOTE: Currently available only when blfunc=’poly’
verbose -- output fitting results to logger. if False, the fitting results
including coefficients, residual rms, etc., are not output to
the CASA logger, while the processing speed gets faster.
options: (bool) True, False
default: True
bloutput -- output fitting results to a text file. if False, the fitting
results including coefficients, residual rms, etc., are not
output to a text file (<outfile>_blparam.txt), while
the processing speed gets faster.
options: (bool) True, False
default: True
blformat -- format of the logger output and text file specified with bloutput
options: ’’, ’csv’
default: ’’ (same as in the past, easy to read but huge)
showprogress -- show progress status for large data
options: (bool) True, False
default: True
>>> showprogress expandable parameter
minnrow -- minimum number of input spectra to show progress status
default: 1000
outfile -- name of output file
default: ’’ (<infile>_bs)
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: 0, 1, 2, or <0
default: 0 (no plotting)
example: 0 (no plotting)
1 (some)
2 (more)
<0 (hardcopy) as abs(plotlevel), e.g.
-1 => hardcopy of final plot (will be named
<outfile>_bspec.eps)
-----------
DESCRIPTION
-----------
Task sdbaselineold performs baseline fitting/removal for single-dish spectra.
The fit parameters, terms and rms of baseline are saved to an ascii
file, ’<outfile>_blparam.txt’ if bloutput is True.
-----------------------
BASELINE MODEL FUNCTION
-----------------------
The list of available model functions are shown above (see Keyword arguments
section). In general ’cspline’ or ’chebyshev’ are recommended since they are
more stable than others. ’poly’ will work for lower order but will be unstable
for higher order fitting. ’sinusoid’ is kind of special mode that will be
useful for the data that clearly shows standing wave in the spectral baseline.
----------------------------------
SIGMA CLIPPING (ITERATIVE FITTING)
----------------------------------
In general least square fitting is strongly affected by an extreme data
so that the resulting fit makes worse. Sigma clipping is an iterative
baseline fitting with data clipping based on a certain threshold. Threshold
is set as a certain factor times rms of the resulting (baseline subtracted)
spectra. If sigma clipping is on, baseline fit/removal is performed several
times. After each baseline subtraction, the data whose absolute value is
above threshold are detected and those data are excluded from the next round
of fitting. By using sigma clipping, extreme data are excluded from the
fit so that resulting fit is more robust.
The user is able to control a multiplication factor using parameter
clipthresh for clipping threshold based on rms. Actual threshold for sigma
clipping will be (clipthresh) x (rms of spectra). Also, the user can specify
number of maximum iteration to the parameter clipniter.
In general, sigma clipping will lower the performance since it increases
number of fits per spectra. However, it is strongly recommended to turn
on sigma clipping unless you are sure that the data is free from any kind
of extreme values that may affect the fit.
--------------------
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 sdbaselineold 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