Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/apparentsens.py: 56%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 17:39 +0000
1##################### generated by xml-casa (v2) from apparentsens.xml ##############
2##################### 9d6c5795d9dfba6821c2263a4b3cb80f ##############################
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_apparentsens import apparentsens as _apparentsens_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 _apparentsens:
15 """
16 apparentsens ---- Imaging sensitivity estimation
18 Estimates the expected imaging sensitivity as a function of the
19 visibility weights and imaging parameters.
21 --------- parameter descriptions ---------------------------------------------
23 vis Name(s) of input visibility file(s)
24 default: none;
25 example: vis='ngc5921.ms'
26 vis=['ngc5921a.ms','ngc5921b.ms']; multiple MSes
27 field Select fields to image or mosaic. Use field id(s) or name(s).
28 ['go listobs' to obtain the list id's or names]
29 default: ''= all fields
30 If field string is a non-negative integer, it is assumed to
31 be a field index otherwise, it is assumed to be a
32 field name
33 field='0~2'; field ids 0,1,2
34 field='0,4,5~7'; field ids 0,4,5,6,7
35 field='3C286,3C295'; field named 3C286 and 3C295
36 field = '3,4C*'; field id 3, all names starting with 4C
37 For multiple MS input, a list of field strings can be used:
38 field = ['0~2','0~4']; field ids 0-2 for the first MS and 0-4
39 for the second
40 field = '0~2'; field ids 0-2 for all input MSes
41 spw Select spectral window/channels
42 NOTE: channels de-selected here will contain all zeros if
43 selected by the parameter mode subparameters.
44 default: ''=all spectral windows and channels
45 spw='0~2,4'; spectral windows 0,1,2,4 (all channels)
46 spw='0:5~61'; spw 0, channels 5 to 61
47 spw='<2'; spectral windows less than 2 (i.e. 0,1)
48 spw='0,10,3:3~45'; spw 0,10 all channels, spw 3,
49 channels 3 to 45.
50 spw='0~2:2~6'; spw 0,1,2 with channels 2 through 6 in each.
51 For multiple MS input, a list of spw strings can be used:
52 spw=['0','0~3']; spw ids 0 for the first MS and 0-3 for the second
53 spw='0~3' spw ids 0-3 for all input MS
54 spw='3:10~20;50~60' for multiple channel ranges within spw id 3
55 spw='3:10~20;50~60,4:0~30' for different channel ranges for spw ids 3 and 4
56 spw='0:0~10,1:20~30,2:1;2;3'; spw 0, channels 0-10,
57 spw 1, channels 20-30, and spw 2, channels, 1,2 and 3
58 spw='1~4;6:15~48' for channels 15 through 48 for spw ids 1,2,3,4 and 6
59 intent Scan Intent(s)
61 default: '' (all)
62 example: intent='TARGET_SOURCE'
63 example: intent='TARGET_SOURCE1,TARGET_SOURCE2'
64 example: intent='TARGET_POINTING*'
65 selectdata Enable data selection parameters.
66 timerange Range of time to select from data
68 default: '' (all); examples,
69 timerange = 'YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss'
70 Note: if YYYY/MM/DD is missing date defaults to first
71 day in data set
72 timerange='09:14:0~09:54:0' picks 40 min on first day
73 timerange='25:00:00~27:30:00' picks 1 hr to 3 hr
74 30min on NEXT day
75 timerange='09:44:00' pick data within one integration
76 of time
77 timerange='> 10:24:00' data after this time
78 For multiple MS input, a list of timerange strings can be
79 used:
80 timerange=['09:14:0~09:54:0','> 10:24:00']
81 timerange='09:14:0~09:54:0''; apply the same timerange for
82 all input MSes
83 uvrange Select data within uvrange (default unit is meters)
84 default: '' (all); example:
85 uvrange='0~1000klambda'; uvrange from 0-1000 kilo-lambda
86 uvrange='> 4klambda';uvranges greater than 4 kilo lambda
87 For multiple MS input, a list of uvrange strings can be
88 used:
89 uvrange=['0~1000klambda','100~1000klamda']
90 uvrange='0~1000klambda'; apply 0-1000 kilo-lambda for all
91 input MSes
92 antenna Select data based on antenna/baseline
94 default: '' (all)
95 If antenna string is a non-negative integer, it is
96 assumed to be an antenna index, otherwise, it is
97 considered an antenna name.
98 antenna='5\&6'; baseline between antenna index 5 and
99 index 6.
100 antenna='VA05\&VA06'; baseline between VLA antenna 5
101 and 6.
102 antenna='5\&6;7\&8'; baselines 5-6 and 7-8
103 antenna='5'; all baselines with antenna index 5
104 antenna='05'; all baselines with antenna number 05
105 (VLA old name)
106 antenna='5,6,9'; all baselines with antennas 5,6,9
107 index number
108 For multiple MS input, a list of antenna strings can be
109 used:
110 antenna=['5','5\&6'];
111 antenna='5'; antenna index 5 for all input MSes
112 antenna='!DV14'; use all antennas except DV14
113 scan Scan number range
115 default: '' (all)
116 example: scan='1~5'
117 For multiple MS input, a list of scan strings can be used:
118 scan=['0~100','10~200']
119 scan='0~100; scan ids 0-100 for all input MSes
120 observation Observation ID range
121 default: '' (all)
122 example: observation='1~5'
123 imsize Number of pixels
124 example : imsize = [350,250]
125 imsize = 500 is equivalent to [500,500]
126 To take proper advantage of internal optimized FFT routines, the
127 number of pixels must be even and factorizable by 2,3,5,7 only.
128 cell Cell size
129 example: cell=['0.5arcsec,'0.5arcsec'] or
130 cell=['1arcmin', '1arcmin']
131 cell = '1arcsec' is equivalent to ['1arcsec','1arcsec']
132 stokes Stokes Planes to make (I only, for now)
133 default='I'; example: stokes='IQUV';
134 Options: 'I','Q','U','V','IV','QU','IQ','UV','IQUV','RR','LL','XX','YY','RRLL','XXYY','pseudoI'
136 Note : Due to current internal code constraints, if any correlation pair
137 is flagged, by default, no data for that row in the MS will be used.
138 So, in an MS with XX,YY, if only YY is flagged, neither a
139 Stokes I image nor an XX image can be made from those data points.
140 In such a situation, please split out only the unflagged correlation into
141 a separate MS.
143 Note : The 'pseudoI' option is a partial solution, allowing Stokes I imaging
144 when either of the parallel-hand correlations are unflagged.
146 The remaining constraints shall be removed (where logical) in a future release.
147 specmode Spectral definition mode (mfs only, for now)
149 mode='mfs' : Continuum imaging with only one output image channel.
150 (mode='cont' can also be used here)
152 mode='cube' : Spectral line imaging with one or more channels
153 Parameters start, width,and nchan define the spectral
154 coordinate system and can be specified either in terms
155 of channel numbers, frequency or velocity in whatever
156 spectral frame is specified in 'outframe'.
157 All internal and output images are made with outframe as the
158 base spectral frame. However imaging code internally uses the fixed
159 spectral frame, LSRK for automatic internal software
160 Doppler tracking so that a spectral line observed over an
161 extended time range will line up appropriately.
162 Therefore the output images have additional spectral frame conversion
163 layer in LSRK on the top the base frame.
166 (Note : Even if the input parameters are specified in a frame
167 other than LSRK, the viewer still displays spectral
168 axis in LSRK by default because of the conversion frame
169 layer mentioned above. The viewer can be used to relabel
170 the spectral axis in any desired frame - via the spectral
171 reference option under axis label properties in the
172 data display options window.)
177 mode='cubedata' : Spectral line imaging with one or more channels
178 There is no internal software Doppler tracking so
179 a spectral line observed over an extended time range
180 may be smeared out in frequency. There is strictly
181 no valid spectral frame with which to label the output
182 images, but they will list the frame defined in the MS.
183 weighting Weighting scheme (natural,uniform,briggs,superuniform,radial)
185 During gridding of the dirty or residual image, each visibility value is
186 multiplied by a weight before it is accumulated on the uv-grid.
187 The PSF's uv-grid is generated by gridding only the weights (weightgrid).
189 weighting='natural' : Gridding weights are identical to the data weights
190 from the MS. For visibilities with similar data weights,
191 the weightgrid will follow the sample density
192 pattern on the uv-plane. This weighting scheme
193 provides the maximum imaging sensitivity at the
194 expense of a possibly fat PSF with high sidelobes.
195 It is most appropriate for detection experiments
196 where sensitivity is most important.
198 weighting='uniform' : Gridding weights per visibility data point are the
199 original data weights divided by the total weight of
200 all data points that map to the same uv grid cell :
201 ' data_weight / total_wt_per_cell '.
203 The weightgrid is as close to flat as possible resulting
204 in a PSF with a narrow main lobe and suppressed
205 sidelobes. However, since heavily sampled areas of
206 the uv-plane get down-weighted, the imaging
207 sensitivity is not as high as with natural weighting.
208 It is most appropriate for imaging experiments where
209 a well behaved PSF can help the reconstruction.
211 weighting='briggs' : Gridding weights per visibility data point are given by
212 'data_weight / ( A / total_wt_per_cell + B ) ' where
213 A and B vary according to the 'robust' parameter.
215 robust = -2.0 maps to A=1,B=0 or uniform weighting.
216 robust = +2.0 maps to natural weighting.
217 (robust=0.5 is equivalent to robust=0.0 in AIPS IMAGR.)
219 Robust/Briggs weighting generates a PSF that can
220 vary smoothly between 'natural' and 'uniform' and
221 allow customized trade-offs between PSF shape and
222 imaging sensitivity.
224 weighting='superuniform' : This is similar to uniform weighting except that
225 the total_wt_per_cell is replaced by the
226 total_wt_within_NxN_cells around the uv cell of
227 interest. ( N = subparameter 'npixels' )
229 This method tends to give a PSF with inner
230 sidelobes that are suppressed as in uniform
231 weighting but with far-out sidelobes closer to
232 natural weighting. The peak sensitivity is also
233 closer to natural weighting.
235 weighting='radial' : Gridding weights are given by ' data_weight * uvdistance '
237 This method approximately minimizes rms sidelobes
238 for an east-west synthesis array.
240 For more details on weighting please see Chapter3
241 of Dan Briggs' thesis (http://www.aoc.nrao.edu/dissertations/dbriggs)
242 robust Robustness parameter for Briggs weighting.
244 robust = -2.0 maps to uniform weighting.
245 robust = +2.0 maps to natural weighting.
246 (robust=0.5 is equivalent to robust=0.0 in AIPS IMAGR.)
247 npixels Number of pixels to determine uv-cell size for super-uniform weighting
248 (0 defaults to -/+ 3 pixels)
250 npixels -- uv-box used for weight calculation
251 a box going from -npixel/2 to +npixel/2 on each side
252 around a point is used to calculate weight density.
254 npixels=2 goes from -1 to +1 and covers 3 pixels on a side.
256 npixels=0 implies a single pixel, which does not make sense for
257 superuniform weighting. Therefore, if npixels=0 it will
258 be forced to 6 (or a box of -3pixels to +3pixels) to cover
259 7 pixels on a side.
260 uvtaper uv-taper on outer baselines in uv-plane
262 Apply a Gaussian taper in addition to the weighting scheme specified
263 via the 'weighting' parameter. Higher spatial frequencies are weighted
264 down relative to lower spatial frequencies to suppress artifacts
265 arising from poorly sampled areas of the uv-plane. It is equivalent to
266 smoothing the PSF obtained by other weighting schemes and can be
267 specified either as a Gaussian in uv-space (eg. units of lambda)
268 or as a Gaussian in the image domain (eg. angular units like arcsec).
270 uvtaper = [bmaj, bmin, bpa]
272 NOTE: the on-sky FWHM in arcsec is roughly the uv taper/200 (klambda).
273 default: uvtaper=[]; no Gaussian taper applied
274 example: uvtaper=['5klambda'] circular taper
275 FWHM=5 kilo-lambda
276 uvtaper=['5klambda','3klambda','45.0deg']
277 uvtaper=['10arcsec'] on-sky FWHM 10 arcseconds
278 uvtaper=['300.0'] default units are lambda
279 in aperture plane
280 [1;42mRETURNS[1;m record
282 --------- examples -----------------------------------------------------------
286 TBD.
291 """
293 _info_group_ = """imaging"""
294 _info_desc_ = """Imaging sensitivity estimation"""
296 def __call__( self, vis='', field='', spw='', intent='', selectdata=True, timerange='', uvrange='', antenna='', scan='', observation='', imsize=[ int(100) ], cell=[ ], stokes='I', specmode='mfs', weighting='natural', robust=float(0.5), npixels=int(0), uvtaper=[ '' ] ):
297 schema = {'vis': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'field': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'spw': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'intent': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'selectdata': {'type': 'cBool'}, 'timerange': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'uvrange': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'antenna': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'scan': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'observation': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cInt'}]}, 'imsize': {'anyof': [{'type': 'cInt'}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}]}, 'cell': {'anyof': [{'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, {'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cFloat', 'coerce': _coerce.to_float}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, {'type': 'cInt'}, {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}]}, 'stokes': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'I', 'IQUV', 'UV', 'RRLL', 'IQ', 'V', 'pseudoI', 'QU', 'YY', 'RR', 'Q', 'U', 'IV', 'XX', 'XXYY', 'LL' ]}, 'specmode': {'type': 'cVariant', 'coerce': [_coerce.to_variant] # <allowed> IS NOT ALLOWED FOR A PARAMETER OF TYPE any
298}, 'weighting': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'briggs', 'natural', 'radial', 'superuniform', 'uniform' ]}, 'robust': {'type': 'cFloat', 'coerce': _coerce.to_float, 'min': -2.0, 'max': 2.0}, 'npixels': {'type': 'cInt'}, 'uvtaper': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}}
299 doc = {'vis': vis, 'field': field, 'spw': spw, 'intent': intent, 'selectdata': selectdata, 'timerange': timerange, 'uvrange': uvrange, 'antenna': antenna, 'scan': scan, 'observation': observation, 'imsize': imsize, 'cell': cell, 'stokes': stokes, 'specmode': specmode, 'weighting': weighting, 'robust': robust, 'npixels': npixels, 'uvtaper': uvtaper}
300 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
301 _logging_state_ = _start_log( 'apparentsens', [ 'vis=' + repr(_pc.document['vis']), 'field=' + repr(_pc.document['field']), 'spw=' + repr(_pc.document['spw']), 'intent=' + repr(_pc.document['intent']), 'selectdata=' + repr(_pc.document['selectdata']), 'timerange=' + repr(_pc.document['timerange']), 'uvrange=' + repr(_pc.document['uvrange']), 'antenna=' + repr(_pc.document['antenna']), 'scan=' + repr(_pc.document['scan']), 'observation=' + repr(_pc.document['observation']), 'imsize=' + repr(_pc.document['imsize']), 'cell=' + repr(_pc.document['cell']), 'stokes=' + repr(_pc.document['stokes']), 'specmode=' + repr(_pc.document['specmode']), 'weighting=' + repr(_pc.document['weighting']), 'robust=' + repr(_pc.document['robust']), 'npixels=' + repr(_pc.document['npixels']), 'uvtaper=' + repr(_pc.document['uvtaper']) ] )
302 task_result = None
303 try:
304 task_result = _apparentsens_t( _pc.document['vis'], _pc.document['field'], _pc.document['spw'], _pc.document['intent'], _pc.document['selectdata'], _pc.document['timerange'], _pc.document['uvrange'], _pc.document['antenna'], _pc.document['scan'], _pc.document['observation'], _pc.document['imsize'], _pc.document['cell'], _pc.document['stokes'], _pc.document['specmode'], _pc.document['weighting'], _pc.document['robust'], _pc.document['npixels'], _pc.document['uvtaper'] )
305 except Exception as exc:
306 _except_log('apparentsens', exc)
307 raise
308 finally:
309 task_result = _end_log( _logging_state_, 'apparentsens', task_result )
310 return task_result
312apparentsens = _apparentsens( )