Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/widebandpbcor.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 widebandpbcor.xml ############# 

2##################### 16e4031e46f432d427545ca38fcd9618 ############################## 

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_widebandpbcor import widebandpbcor as _widebandpbcor_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 _widebandpbcor: 

15 """ 

16 widebandpbcor ---- Wideband PB-correction on the output of the MS-MFS algorithm 

17 

18 WideBand Primary-beam correction. It computes a set of PBs at the specified frequencies, calculates Taylor-coefficient images that represent the PB spectrum, performs a polynomial division to PB-correct the output Taylor-coefficient images from clean(nterms>1), and recompute spectral index (and curvature) using the PB-corrected Taylor-coefficient images. 

19 

20 --------- parameter descriptions --------------------------------------------- 

21 

22 vis Name of measurement set. 

23 imagename Name-prefix of multi-termimages to operate on. 

24 nterms Number of taylor terms to use 

25 threshold Intensity above which to re-calculate spectral index 

26 action PB-correction (pbcor) or only calc spectral-index (calcalpha) 

27 reffreq Reference frequency (if specified in clean) 

28 pbmin PB threshold below which to not correct 

29 field Fields to include in the PB calculation 

30 spwlist List of N spw ids 

31 chanlist List of N channel ids 

32 weightlist List of N weights (relative) 

33 RETURNS void 

34 

35 --------- examples ----------------------------------------------------------- 

36 

37  

38  

39 Wide-band Primary-beam correction 

40  

41 (1) Compute a set of Primary Beams at the specified frequencies 

42 (2) Calculate Taylor-coefficient images that represent the PB spectrum 

43 (3) Perform a polynomial division to PB-correct the output Taylor-coefficient 

44 images from the MS-MFS algorithm ( clean(nterms>1) ) 

45 (4) Recompute spectral index (and curvature) using the corrected Taylor-coefficient images. 

46  

47 [ Optionally, skip PB-correction, and only recalculate spectral index 

48 with a different threshold ] 

49  

50 This is a temporary task, meant for use until a widebandpbcor option is enabled from 

51 within the tclean task. 

52  

53 An output directory named imagename.pbcor.workdirectory is created, and filled with 

54 an image-cube of the evaluated primary beams at all specified frequencies, 

55 Taylor-coefficients, and a 'spectral index' due to the primary beam. 

56 Note that for the actual pb-correction, only the Taylor-coefficient images are used. 

57  

58 Task parameters : 

59  

60 vis -- Name of input visibility file 

61 example : vis = 'ngc5921.ms' 

62 Only one MS can be specified here, and it must contain at-least one 

63 timestep of data at all frequencies required to calculate the PB spectrum. 

64  

65 Note : If the imaging was done using a list of MSs, and any one MS covers 

66 the entire frequency range, then it will suffice to supply only that one 

67 MS. This MS is used only to extract frequencies at which to compute 

68 primary beams before fitting Taylor polynomials. 

69  

70 Note : In case of multiple MSs that cover different frequency ranges, 

71 please split/concat a small fraction of the data from each MS to form 

72 one single MS that contains the full frequency range. This task uses 

73 the MS only for frequency meta-data. 

74  

75 imagename -- Pre-name of input and output images. Same as in the clean task. 

76 example : imagename = 'run1' 

77 Restored-images ( run1.image.tt0,etc) and residual images ( run1.residual.tt0, etc.. ) 

78 must be available on disk. 

79  

80 nterms -- Number of Taylor terms to be used to model the frequency-dependence 

81 of the primary beam. 

82 example : nterms = 2 

83 nterms must be less than or equal to the number of frequencies specified via 

84 spwlist, chanlist and weightlist. 

85 nterms=1 will do a standard division by the average PB computed over all 

86 specified frequencies. 

87  

88 threshold -- Flux level in the restored intensity map, below which to not 

89 recalculate spectral index. 

90 example : threshold = '0.1Jy' 

91  

92 action -- Choice of PB-correction with spectral-index recalculation 

93 or only spectral-index recalculation (using the specified threshold) 

94 example : action='pbcor' or action='calcalpha' 

95  

96 With action='pbcor', the following output images are created/overwritten. 

97  

98 - imagename.pbcor.workdirectory : This directory contains an image cube with 

99 PBs at the list of specified frequencies, and Taylor-coefficient images that 

100 describe the PB spectrum. 

101 - imagename.pb.cube : Concatenated cube of PBs 

102 - imagename.pb.tt0, tt1, ... : Taylor coefficients describing the PB spectrum 

103 - imagename.pb.alpha : Spectral index of the PB (for information only) 

104 - imagename.image.pbcor.tt0,tt1,... : Corrected Taylor coefficients 

105 - imagename.pbcor.image.alpha : Corrected Spectral Index 

106 - imagename.pbcor.image.alpha.error : New error map. 

107  

108 With action='calcalpha', the following output images are created/overwritten 

109 - imagename.image.alpha : Corrected Spectral Index 

110 - imagename.image.alpha.error : New error map. 

111  

112 reffreq -- Reference frequency about which the Taylor-expansion is defined. 

113 example : reffreq = '1.5GHz' 

114 If left unspecified, it is picked from the input restored image. 

115 Note : If reffreq was specified during task clean to produce the images 

116 it must be specified here. 

117  

118 pbmin -- PB gain level below which to not compute Taylor-coefficients or 

119 apply PB-corrections. 

120 example : pbmin = 0.1 

121  

122 field -- Field selection for the Primary Beam calculation. 

123 example : field = '3C291' 

124 This field selection must be identical to that used in 'clean' 

125  

126 spwlist -- List of SPW ids for which to make separate Primary Beams 

127 chanlist -- List of channel ids, within the above SPW ids, at which to make PBs. 

128  

129 example : spwlist=[0,1,2], chanlist=[32,32,32] 

130 Make PBs at frequencies corresponding to channel 32 of 

131 spws 0,1 and 2. 

132 example : spwlist=[0,0,0], chanlist=[0,10,20] 

133 Make PBs at frequencies corresponding to channels 0,10,20 

134 of spw 0 

135  

136 Primary beams are computed at these specified frequencies and 

137 for pointings selected by 'field'. Taylor-coefficients that represent 

138 the PB spectrum are computed from these images. 

139  

140 weightlist -- List of relative weights to apply to the PBs selected via the 

141 spwlist,chanlist parameters. Weights should approximately represent the 

142 sum-of-weights applicable during imaging each of these frequencies. 

143 example : weightlist=[0.5,1.0,1.0] 

144 The first frequency had less usable data due to flagged RFI, 

145 but the other two had relatively equal weight. 

146 These weights are applied to the PB spectrum while computing 

147 PB Taylor-coefficients. Setting weights to anything other than 1.0 

148 makes a difference only with very lop-sided weights. 

149  

150  

151 NOTE : One frequently asked question relates to how best to choose spwlist,chanlist,weightlist. 

152  

153 The basic principles at work here are 

154  

155 (1) Imaging = fitting a polynomial to a noisy spectrum (with weights). 

156 The polynomial represents I(nu) x P(nu) 

157  

158 (2) PB model = fitting a polynomial to a collection of PBs at different 

159 frequencies (with weights). The polynomial represents P(nu) 

160  

161 (3) Dividing the two polynomials via their coefficients. 

162  

163 Steps (1) and (2) need to be consistent with each other (w.r.to frequencies used 

164 and their weights) to produce fits that when divided give exactly only the sky parameters. 

165 Unless you use the same math (and code) for both, they won't be exactly consistent. 

166 The way to minimize differences is to choose a list of frequencies (via spws/chans) 

167 and weights for widebandpbcor that resemble the frequency structure of the data you 

168 have used for imaging. 

169 For example, if you have 3 spws in your data and the middle spw has a factor of 10 

170 less weight in the data, then, using just one channel each from the two outer spws for 

171 the PB modeling may be close enough to using all 3 spws. Or, you could also pick 

172 the middle channel of all 3 spws, and assign weights as [1.0, 0.1, 1.0]. 

173  

174  

175  

176 

177 

178 """ 

179 

180 _info_group_ = """imaging""" 

181 _info_desc_ = """Wideband PB-correction on the output of the MS-MFS algorithm""" 

182 

183 def __call__( self, vis='', imagename='', nterms=int(2), threshold='', action='pbcor', reffreq='', pbmin=float(0.2), field='', spwlist=[ int() ], chanlist=[ int() ], weightlist=[ float() ] ): 

184 schema = {'vis': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'imagename': {'type': 'cStr', 'coerce': _coerce.to_str}, 'nterms': {'type': 'cInt'}, 'threshold': {'type': 'cStr', 'coerce': _coerce.to_str}, 'action': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'pbcor', 'calcalpha' ]}, 'reffreq': {'type': 'cStr', 'coerce': _coerce.to_str}, 'pbmin': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'field': {'type': 'cStr', 'coerce': _coerce.to_str}, 'spwlist': {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, 'chanlist': {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, 'weightlist': {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}} 

185 doc = {'vis': vis, 'imagename': imagename, 'nterms': nterms, 'threshold': threshold, 'action': action, 'reffreq': reffreq, 'pbmin': pbmin, 'field': field, 'spwlist': spwlist, 'chanlist': chanlist, 'weightlist': weightlist} 

186 assert _pc.validate(doc,schema), create_error_string(_pc.errors) 

187 _logging_state_ = _start_log( 'widebandpbcor', [ 'vis=' + repr(_pc.document['vis']), 'imagename=' + repr(_pc.document['imagename']), 'nterms=' + repr(_pc.document['nterms']), 'threshold=' + repr(_pc.document['threshold']), 'action=' + repr(_pc.document['action']), 'reffreq=' + repr(_pc.document['reffreq']), 'pbmin=' + repr(_pc.document['pbmin']), 'field=' + repr(_pc.document['field']), 'spwlist=' + repr(_pc.document['spwlist']), 'chanlist=' + repr(_pc.document['chanlist']), 'weightlist=' + repr(_pc.document['weightlist']) ] ) 

188 task_result = None 

189 try: 

190 task_result = _widebandpbcor_t( _pc.document['vis'], _pc.document['imagename'], _pc.document['nterms'], _pc.document['threshold'], _pc.document['action'], _pc.document['reffreq'], _pc.document['pbmin'], _pc.document['field'], _pc.document['spwlist'], _pc.document['chanlist'], _pc.document['weightlist'] ) 

191 except Exception as exc: 

192 _except_log('widebandpbcor', exc) 

193 raise 

194 finally: 

195 task_result = _end_log( _logging_state_, 'widebandpbcor', task_result ) 

196 return task_result 

197 

198widebandpbcor = _widebandpbcor( ) 

199