|
|||
NRAO Home > CASA > CASA Task Reference Manual |
|
0.1.106 sdfitold
Requires:
Synopsis
ASAP SD task [DEPRECATED]: Fit a spectral line
Description
### DEPRECATION WARNING
#################################################
This task will be removed in CASA 5.1. The functionality of this task with
MeasurementSet format is replicated with sdfit.
#########################################################################
Task sdfitold is a basic line-fitter for single-dish spectra. It assumes that the
spectra have been calibrated in sdcal or sdreduce.
Arguments
Outputs |
| ||
xstat |
| RETURN ONLY: a Python dictionary of line statistics
| |
| allowed: | any |
|
| Default: | variant | |
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: |
|
|
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: |
|
|
timeaverage |
| average spectra over time (see examples in help)
| |
| allowed: | bool |
|
| Default: | False |
|
tweight |
| weighting for time averaging
| |
| allowed: | string |
|
| Default: | tintsys |
|
scanaverage |
| average spectra within a scan number (see examples in
help)
| |
| allowed: | bool |
|
| Default: | False |
|
polaverage |
| average spectra over polarizations
| |
| allowed: | bool |
|
| Default: | False |
|
pweight |
| weighting for polarization averaging
| |
| allowed: | string |
|
| Default: | tsys |
|
fitfunc |
| function for fitting
| |
| allowed: | string |
|
| Default: | gauss |
|
fitmode |
| mode for fitting
| |
| allowed: | string |
|
| Default: | auto |
|
nfit |
| list of number of gaussian/lorentzian lines to fit in in
maskline region (ignored when fitmode=”auto”)
| |
| allowed: | intArray |
|
| Default: |
|
|
thresh |
| S/N threshold for linefinder
| |
| allowed: | double |
|
| Default: | 5.0 |
|
min_nchan |
| minimum number of consecutive channels for linefinder
| |
| allowed: | int |
|
| Default: | 3 |
|
avg_limit |
| channel averaging for broad lines
| |
| allowed: | int |
|
| Default: | 4 |
|
box_size |
| running mean box size
| |
| allowed: | double |
|
| Default: | 0.2 |
|
edge |
| channels to drop at beginning and end of spectrum
| |
| allowed: | intArray |
|
| Default: | 0 |
|
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 |
|
plotlevel |
| control for plotting of results (see examples in help)
| |
| allowed: | int |
|
| Default: | 0 |
|
variant
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)
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
fitfunc -- function for fitting
options: ’gauss’ (Gaussian), ’lorentz’ (Lorentzian)
default: ’gauss’
fitmode -- mode for fitting
options: ’auto’, ’list’, or ’interact’
default: ’auto’
example: ’auto’ will use the linefinder to fit for lines
using the following parameters
’list’ will use maskline to define regions to
fit for lines with nfit in each
’interact’ 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.
>>> fitmode 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
min_nchan -- minimum number of consecutive channels required to
pass threshold
default: 3
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
box_size -- running mean box size specified as a fraction
of the total spectrum length
default: 0.2
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.
nfit -- list of number of gaussian/lorentzian lines to fit in in maskline
region (ignored when fitmode=’auto’)
default: 0 (no fitting)
example: nfit=[1] for single line in single region,
nfit=[2] for two lines in single region,
nfit=[1,1] for single lines in each of two regions, etc.
outfile -- name of output file
default: no output fit file
example: ’mysd.fit’
overwrite -- overwrite the output file if already exists
options: (bool) True, False
default: False
plotlevel -- control for plotting of results
options: 0, 1, 2
default: 0 (no plotting)
example: plotlevel=0 no plotting
plotlevel=1 plots fit
plotlevel=2 plots fit and residual
no hardcopy available for fitter
WARNING: be careful plotting OTF data with lots of fields
-------
Returns
-------
a Python dictionary of line statistics
keys: ’peak’, ’cent’, ’fwhm’, ’nfit’
example: each value is a list of lists with one list of
2 entries [fitvalue,error] per component.
e.g. xstat[’peak’]=[[234.9, 4.8],[234.2, 5.3]]
for 2 components.
-----------
DESCRIPTION
-----------
Task sdfitold is a basic line-fitter for single-dish spectra.
It assumes that the spectra have been calibrated in sdcal
or sdreduce.
Furthermore, it assumes that any selection of scans, IFs,
polarizations, and time and channel averaging/smoothing has
also already been done (in other sd tasks) as there are no controls
for these. Note that you can use sdsave to do selection, writing
out a new scantable.
Note that multiple scans, IFs, and polarizations can in principle
be handled, but we recommend that you use scan, field, spw, and pol
to give a single selection for each fit.
Currently, you can choose Gaussian or Lorentzian profile as a
fitting model.
For complicated spectra, sdfitold does not do a good job of
"auto-guessing" the starting model for the fit. We recommend
you use sd.fitter in the toolkit which has more options, such
as fixing components in the fit and supplying starting guesses
by hand.
-------
FITMODE
-------
As described in the parameter description section, sdfitold implements
three fitting mode, ’auto’, ’list’, and ’interact’. Only difference
between these modes are a method to set initial guess for line fitting.
In ’auto’ mode, initial guess is automatically set by executing line
finder. On the other hand, ’list’ and ’interact’ allow to set initial
guess manually. In these modes, only controllable parameter for the
guess is range of the line region and number of lines per region.
In ’list’ mode, the user must give line region via spw parameter by using
ms selection syntax while number of lines per region can be specified
via nfit parameter. For example,
spw = ’17:1500~2500’
nfit = [1]
will set line region between channels 1500 and 2500 for spw 17, and
indicate that there is only one line in this region. Specifying single
region with multiple line is also possible but is not recommended.
In ’interact’ mode, spectral data to be fitted will be displayed
with pre-defined line region specified by spw parameter. The user is
able to customize line region interactively.
--------------------
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 sdcal 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.
-------------------------------------
AVERAGING OF SPECTRA
-------------------------------------
Task sdfitold 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.
-------
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