Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/sdfit.py: 56%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 18:48 +0000
1##################### generated by xml-casa (v2) from sdfit.xml #####################
2##################### 679654f67f2a3d1872f004dbc2ef87ed ##############################
3from __future__ import absolute_import
4import numpy
5from casatools.typecheck import CasaValidator as _val_ctor
6_pc = _val_ctor( )
7from casatools.coercetype import coerce as _coerce
8from casatools.errors import create_error_string
9from .private.task_sdfit import sdfit as _sdfit_t
10from casatasks.private.task_logging import start_log as _start_log
11from casatasks.private.task_logging import end_log as _end_log
12from casatasks.private.task_logging import except_log as _except_log
14class _sdfit:
15 """
16 sdfit ---- Fit a spectral line
19 Task sdfit is a basic line-fitter for single-dish spectra.
20 It assumes that the spectra have been calibrated in tsdcal
21 or sdreduce.
24 --------- parameter descriptions ---------------------------------------------
26 infile name of input SD dataset
27 datacolumn name of data column to be used ["data", "float_data", or "corrected_data"]
28 antenna select data by antenna name or ID, e.g. "PM03"
29 field select data by field IDs and names, e.g. "3C2*" (""=all)
30 spw select data by IF IDs (spectral windows), e.g. "3,5,7" (""=all)
31 timerange select data by time range, e.g. "09:14:0~09:54:0" (""=all) (see examples in help)
32 scan select data by scan numbers, e.g. "21~23" (""=all)
33 pol select data by polarization IDs, e.g. "XX,YY" (""=all)
34 intent select data by observational intent, e.g. "*ON_SOURCE*" (""=all)
35 timebin bin width for time averaging
36 timespan span the timebin across "scan", "state", "field", or a combination of them (e.g., "scan,state")
37 polaverage polarization averaging mode ("", "stokes" or "geometric").
38 fitfunc function for fitting
39 fitmode mode for setting additional channel masks.
40 nfit list of number of lines to fit in maskline region.
41 thresh S/N threshold for linefinder
42 avg_limit channel averaging for broad lines
43 minwidth the minimum channel width to detect as a line
44 edge channels to drop at beginning and end of spectrum
45 outfile name of output file
46 overwrite overwrite the output file if already exists
47 [1;42mRETURNS[1;m variant
49 --------- examples -----------------------------------------------------------
52 -----------------
53 Keyword arguments
54 -----------------
55 infile -- name of input SD dataset
56 datacolumn -- name of data column to be used
57 options: 'data', 'float_data', or 'corrected_data'
58 default: 'data'
59 antenna -- select data by antenna name or ID
60 default: '' (use all antennas)
61 example: 'PM03'
62 field -- select data by field IDs and names
63 default: '' (use all fields)
64 example: field='3C2*' (all names starting with 3C2)
65 field='0,4,5~7' (field IDs 0,4,5,6,7)
66 field='0,3C273' (field ID 0 or field named 3C273)
67 this selection is in addition to the other selections to data
68 spw -- select data by IF IDs (spectral windows)/channels
69 default: '' (use all IFs and channels)
70 example: spw='3,5,7' (IF IDs 3,5,7; all channels)
71 spw='<2' (IF IDs less than 2, i.e., 0,1; all channels)
72 spw='30~45GHz' (IF IDs with the center frequencies in range 30-45GHz; all channels)
73 spw='0:5~61' (IF ID 0; channels 5 to 61; all channels)
74 spw='3:10~20;50~60' (select multiple channel ranges within IF ID 3)
75 spw='3:10~20,4:0~30' (select different channel ranges for IF IDs 3 and 4)
76 spw='1~4;6:15~48' (for channels 15 through 48 for IF IDs 1,2,3,4 and 6)
77 this selection is in addition to the other selections to data
78 timerange -- select data by time range
79 default: '' (use all)
80 example: timerange = 'YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss'
81 Note: YYYY/MM/DD can be dropped as needed:
82 timerange='09:14:00~09:54:00' # this time range
83 timerange='09:44:00' # data within one integration of time
84 timerange='>10:24:00' # data after this time
85 timerange='09:44:00+00:13:00' #data 13 minutes after time
86 this selection is in addition to the other selections to data
87 scan -- select data by scan numbers
88 default: '' (use all scans)
89 example: scan='21~23' (scan IDs 21,22,23)
90 this selection is in addition to the other selections to data
91 pol -- select data by polarization IDs
92 default: '' (use all polarizations)
93 example: pol='XX,YY' (polarizations XX and YY)
94 this selection is in addition to the other selections to data
95 intent -- select data by observational intent, also referred to as 'scan intent'
96 default: '' (use all scan intents)
97 example: intent='*ON_SOURCE*' (any valid scan-intent expression accepted by the MSSelection module can be specified)
98 this selection is in addition to the other selections to data
99 timebin -- bin width for time averaging. it must be a positive value.
100 default: '' (no averaging over time)
101 example: timebin='1s' (time averaging performed over 1 second bins)
102 >>> timebin expandable parameters
103 timespan -- span the timebin across 'scan', 'state', 'field', or a combination of them (e.g., 'scan,state')
104 default: '' (average each scan, intent and field separately)
105 example: 'scan' time averaging is done across scan ID boundaries
106 polaverage -- polarization averaging mode
107 default: '' (no averaging over polarization)
108 options: '', 'stokes', 'geometric'
109 fitfunc -- function for fitting
110 options: 'gaussian', 'lorentzian'
111 default: 'gaussian'
112 fitmode -- mode for fitting
113 options: 'list' ('auto' and 'interact' will be available later)
114 default: 'list'
115 example: 'list' will use channel ranges specified in the parameter
116 spw to fit for lines
117 'auto' will use the linefinder to fit for lines
118 using the following parameters
119 'interact' allows adding and deleting mask
120 regions by drawing rectangles on the plot
121 with mouse. Draw a rectangle with LEFT-mouse
122 to ADD the region to the mask and with RIGHT-mouse
123 to DELETE the region.
124 >>> fitmode expandable parameters
125 nfit -- list of number of lines to fit in each region specified by the
126 parameter spw (only available in fitmode='list')
127 default: [0] (no fitting)
128 example: nfit=[1] for single line in single region,
129 nfit=[2] for two lines in single region,
130 nfit=[1,1] for single lines in each of two regions, etc.
131 thresh -- S/N threshold for linefinder. a single channel S/N ratio
132 above which the channel is considered to be a detection.
133 (only available in fitmode='auto')
134 default: 5
135 avg_limit -- channel averaging for broad lines. a number of
136 consecutive channels not greater than this parameter
137 can be averaged to search for broad lines.
138 (only available in fitmode='auto')
139 default: 4
140 minwidth -- minimum number of consecutive channels required to
141 pass threshold
142 (only available in fitmode='auto')
143 default: 4
144 edge -- channels to drop at beginning and end of spectrum
145 (only available in fitmode='auto')
146 default: 0
147 example: edge=[1000] drops 1000 channels at beginning AND end.
148 edge=[1000,500] drops 1000 from beginning and 500
149 from end
151 Note: For bad baselines threshold should be increased,
152 and avg_limit decreased (or even switched off completely by
153 setting this parameter to 1) to avoid detecting baseline
154 undulations instead of real lines.
155 outfile -- name of output file
156 default: no output fit file
157 example: 'mysd.fit'
158 overwrite -- overwrite the output file if already exists
159 options: (bool) True, False
160 default: False
162 -------
163 Returns
164 -------
165 a Python dictionary of line statistics
166 keys: 'peak', 'cent', 'fwhm', 'nfit'
167 example: each value except for 'nfit' is a list of lists with
168 a list of 2 entries [fitvalue,error] per component.
169 e.g. xstat['peak']=[[234.9, 4.8],[234.2, 5.3]]
170 for 2 components.
172 -----------
173 DESCRIPTION
174 -----------
175 Task sdfit is a basic line-fitter for single-dish spectra.
176 It assumes that the spectra have been calibrated in tsdcal
177 or sdreduce.
179 Note that multiple scans, IFs, and polarizations can in principle
180 be handled, but we recommend that you use scan, field, spw, and pol
181 to give a single selection for each fit.
183 -------
184 POLARIZATION AVERAGE
185 -------
186 Two modes of polarization averaging are available. The default is
187 'stokes' which is an average based on a formulation of Stokes
188 parameter. In this mode, averaged data is calculated by
189 (XX + YY) / 2 or (RR + LL) / 2. Other option is 'geometric', which
190 is a conventional way of averaging in the field of single-dish
191 data reduction. The averaged data is given by weighted average
192 of XX and YY, or RR and LL.
194 -------
195 FITMODE
196 -------
197 As described in the parameter description section, sdfit implements
198 fitting modes 'list' and 'auto' so far.
199 The 'list' mode allows users to set initial guess manually. The only
200 controllable parameter for the guess is range of the line region and
201 number of lines per region. In 'list' mode, users must give line
202 region via spw parameter by using ms selection syntax while number of
203 lines per region can be specified via nfit parameter. For example,
205 spw = '17:1500~2500'
206 nfit = [1]
208 will set line region between channels 1500 and 2500 for spw 17, and
209 indicate that there is only one line in this region. Specifying single
210 region with multiple line is also possible but is not recommended.
211 In 'auto' mode, the line finder detects channel ranges of spectral lines
212 based on median absolute deviation (MAD) of the spectra using user defined
213 criteria, thres, avg_limit, minwidth, and edge. The number of channels
214 in both edges of spectra defined by edge parameter are ignored in line
215 detection. The median of lower 80% of MAD values in a spectrum is
216 multiplied by thres parameter value to define a threshold of line
217 detection. All channels with MAD above the threshold is detected as
218 spectral line candidates and accepted as spectral lines only if the
219 channel width of the line exceeds the value of minwidth parameter. The
220 line detection is iteratively invoked for channel averaged spectra
221 up to avg_limit.
226 """
228 _info_group_ = """single dish"""
229 _info_desc_ = """Fit a spectral line"""
231 def __call__( self, infile='', datacolumn='data', antenna='', field='', spw='', timerange='', scan='', pol='', intent='', timebin='', timespan='', polaverage='', fitfunc='gaussian', fitmode='list', nfit=[ int(0) ], thresh=float(5.0), avg_limit=int(4), minwidth=int(4), edge=[ int(0),int(0) ], outfile='', overwrite=False ):
232 schema = {'infile': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'datacolumn': {'type': 'cStr', 'coerce': _coerce.to_str}, 'antenna': {'type': 'cStr', 'coerce': _coerce.to_str}, 'field': {'type': 'cStr', 'coerce': _coerce.to_str}, 'spw': {'type': 'cStr', 'coerce': _coerce.to_str}, 'timerange': {'type': 'cStr', 'coerce': _coerce.to_str}, 'scan': {'type': 'cStr', 'coerce': _coerce.to_str}, 'pol': {'type': 'cStr', 'coerce': _coerce.to_str}, 'intent': {'type': 'cStr', 'coerce': _coerce.to_str}, 'timebin': {'type': 'cStr', 'coerce': _coerce.to_str}, 'timespan': {'type': 'cStr', 'coerce': _coerce.to_str}, 'polaverage': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ '', 'stokes', 'geometric' ]}, 'fitfunc': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'gaussian', 'lorentzian' ]}, 'fitmode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'auto', 'list' ]}, 'nfit': {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, 'thresh': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'avg_limit': {'type': 'cInt'}, 'minwidth': {'type': 'cInt'}, 'edge': {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, 'outfile': {'type': 'cStr', 'coerce': _coerce.to_str}, 'overwrite': {'type': 'cBool'}}
233 doc = {'infile': infile, 'datacolumn': datacolumn, 'antenna': antenna, 'field': field, 'spw': spw, 'timerange': timerange, 'scan': scan, 'pol': pol, 'intent': intent, 'timebin': timebin, 'timespan': timespan, 'polaverage': polaverage, 'fitfunc': fitfunc, 'fitmode': fitmode, 'nfit': nfit, 'thresh': thresh, 'avg_limit': avg_limit, 'minwidth': minwidth, 'edge': edge, 'outfile': outfile, 'overwrite': overwrite}
234 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
235 _logging_state_ = _start_log( 'sdfit', [ 'infile=' + repr(_pc.document['infile']), 'datacolumn=' + repr(_pc.document['datacolumn']), 'antenna=' + repr(_pc.document['antenna']), 'field=' + repr(_pc.document['field']), 'spw=' + repr(_pc.document['spw']), 'timerange=' + repr(_pc.document['timerange']), 'scan=' + repr(_pc.document['scan']), 'pol=' + repr(_pc.document['pol']), 'intent=' + repr(_pc.document['intent']), 'timebin=' + repr(_pc.document['timebin']), 'timespan=' + repr(_pc.document['timespan']), 'polaverage=' + repr(_pc.document['polaverage']), 'fitfunc=' + repr(_pc.document['fitfunc']), 'fitmode=' + repr(_pc.document['fitmode']), 'nfit=' + repr(_pc.document['nfit']), 'thresh=' + repr(_pc.document['thresh']), 'avg_limit=' + repr(_pc.document['avg_limit']), 'minwidth=' + repr(_pc.document['minwidth']), 'edge=' + repr(_pc.document['edge']), 'outfile=' + repr(_pc.document['outfile']), 'overwrite=' + repr(_pc.document['overwrite']) ] )
236 task_result = None
237 try:
238 task_result = _sdfit_t( _pc.document['infile'], _pc.document['datacolumn'], _pc.document['antenna'], _pc.document['field'], _pc.document['spw'], _pc.document['timerange'], _pc.document['scan'], _pc.document['pol'], _pc.document['intent'], _pc.document['timebin'], _pc.document['timespan'], _pc.document['polaverage'], _pc.document['fitfunc'], _pc.document['fitmode'], _pc.document['nfit'], _pc.document['thresh'], _pc.document['avg_limit'], _pc.document['minwidth'], _pc.document['edge'], _pc.document['outfile'], _pc.document['overwrite'] )
239 except Exception as exc:
240 _except_log('sdfit', exc)
241 raise
242 finally:
243 task_result = _end_log( _logging_state_, 'sdfit', task_result )
244 return task_result
246sdfit = _sdfit( )