Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/widebandpbcor.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 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
14class _widebandpbcor:
15 """
16 widebandpbcor ---- Wideband PB-correction on the output of the MS-MFS algorithm
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.
20 --------- parameter descriptions ---------------------------------------------
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 [1;42mRETURNS[1;m void
35 --------- examples -----------------------------------------------------------
39 Wide-band Primary-beam correction
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.
47 [ Optionally, skip PB-correction, and only recalculate spectral index
48 with a different threshold ]
50 This is a temporary task, meant for use until a widebandpbcor option is enabled from
51 within the tclean task.
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.
58 Task parameters :
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.
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.
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.
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.
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.
88 threshold -- Flux level in the restored intensity map, below which to not
89 recalculate spectral index.
90 example : threshold = '0.1Jy'
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'
96 With action='pbcor', the following output images are created/overwritten.
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.
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.
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.
118 pbmin -- PB gain level below which to not compute Taylor-coefficients or
119 apply PB-corrections.
120 example : pbmin = 0.1
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'
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.
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
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.
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.
151 NOTE : One frequently asked question relates to how best to choose spwlist,chanlist,weightlist.
153 The basic principles at work here are
155 (1) Imaging = fitting a polynomial to a noisy spectrum (with weights).
156 The polynomial represents I(nu) x P(nu)
158 (2) PB model = fitting a polynomial to a collection of PBs at different
159 frequencies (with weights). The polynomial represents P(nu)
161 (3) Dividing the two polynomials via their coefficients.
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].
178 """
180 _info_group_ = """imaging"""
181 _info_desc_ = """Wideband PB-correction on the output of the MS-MFS algorithm"""
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
198widebandpbcor = _widebandpbcor( )