Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/sdfit.py: 89%

27 statements  

« prev     ^ index     » next       coverage.py v7.6.4, created at 2024-11-01 07:19 +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 

13 

14class _sdfit: 

15 """ 

16 sdfit ---- Fit a spectral line 

17 

18  

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. 

22  

23 

24 --------- parameter descriptions --------------------------------------------- 

25 

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 RETURNS variant 

48 

49 --------- examples ----------------------------------------------------------- 

50 

51  

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 

150  

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 

161  

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. 

171  

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. 

178  

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. 

182  

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. 

193  

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, 

204  

205 spw = '17:1500~2500' 

206 nfit = [1] 

207  

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. 

222  

223  

224 

225 

226 """ 

227 

228 _info_group_ = """single dish""" 

229 _info_desc_ = """Fit a spectral line""" 

230 

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 

245 

246sdfit = _sdfit( ) 

247