Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/setjy.py: 89%
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 setjy.xml #####################
2##################### 00ebb1489d4e63a2ce3f6c2e5a10db6e ##############################
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_setjy import setjy as _setjy_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 _setjy:
15 """
16 setjy ---- Fills the model column with the visibilities of a calibrator
19 This task places the model visibility amp and phase associated with a
20 specified clean components image into the model column of the data
21 set. The flux density (I,Q,U,V) for a point source calibrator can be
22 entered explicitly.
24 setjy need only be run on the calibrator sources with a known flux
25 density and/or model.
27 Models are available in CASA for 3C48, 3C138, 3C286, and 3C147 between 230 MHz
28 and 43 GHz. In addition, P-band models for the frequency range between 230 -
29 470 MHz are available in CASA for 3C123, 3C196, 3C295, and 3C380.
30 These models are scaled to the precise frequency of the data. Only I models are
31 presently available.
33 For Solar System Objects, model determination was updated and it is
34 available via the 'Butler-JPL-Horizons 2012' standard. Currently they
35 are modeled as uniformtemperature disks based on their ephemeris at
36 the time of observation (note that this may oversimplify objects, in
37 particular asteroids). Specify the name of the object in the 'field'
38 parameter.
40 The location of the models is system dependent: At the AOC, the
41 models are in the directory::/usr/lib/casapy/data/nrao/VLA/CalModels/
42 3C286_L.im (egs).
44 --------- parameter descriptions ---------------------------------------------
46 vis Name of input visibility file
47 Default: none
49 Example: vis='ngc5921.ms'
50 field Select field using field id(s) or field name(s)
51 Default: '' (all fields, but run setjy one field
52 at a time)
54 Use 'go listobs' to obtain the list id's or
55 names. If field string is a non-negative integer,
56 it is assumed a field index, otherwise, it is
57 assumed a field name.
59 Examples:
60 field='0~2'; field ids 0,1,2
61 field='0,4,5~7'; field ids 0,4,5,6,7
62 field='3C286,3C295'; field named 3C286 and
63 3C295
64 field = '3,4C*'; field id 3, all names
65 starting with 4C
66 Field name(s)
67 spw Select spectral window/channels
68 Default: '' (all spectral windows)
70 NOTE: setjy only selects by spectral window, and
71 ignores channel selections. Fine-grained control
72 could be achieved using (and possibly
73 constructing) a cube for model.
74 selectdata Other parameters for selecting part(s) of the MS to
75 operate on.
76 Default: False
77 Options: False|True
79 Currently all time-oriented and most likely only
80 of interest when using a Solar System object as a
81 calibrator.
82 timerange Select data based on time range
83 Subparameter of selectdata=True
84 Default = '' (all)
86 Examples:
87 timerange =
88 'YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss'
89 (Note: if YYYY/MM/DD is missing date defaults
90 to first day in data set.)
91 timerange='09:14:0~09:54:0' picks 40 min on
92 first day
93 timerange= '25:00:00~27:30:00' picks 1 hr to 3
94 hr 30min on NEXT day
95 timerange='09:44:00' pick data within one
96 integration of time
97 timerange='>10:24:00' data after this time
98 scan Scan number range
99 Subparameter of selectdata=True
100 Default: '' = all
102 Example:scan='1~5'
104 For multiple MS input, a list of scan strings can
105 be used:
106 scan=['0~100','10~200']
107 scan='0~100; scan ids 0-100 for all input MSes
108 Check 'go listobs' to insure the scan numbers are
109 in order.
110 intent Select observing intent
111 Default: '' (all
113 Example: using wildcard characters,
114 intent="*CALIBRATE_AMPLI*" will match field(s)
115 contains CALIBRATE_AMPLI in a list of intents
117 WARNING: If a source with a specific field id has
118 scans that can be distinguishable with intent
119 selection, one should set
120 usescatch=True. Otherwise, any existing model of
121 the source may be cleared and overwritten even if
122 the part of the scans not selected by intent.
123 observation Select by observation ID(s)
124 Subparameter of selectdata=True
125 Default: '' = all
127 Example: observation='0~2,4'
128 scalebychan Scale the flux density on a per channel basis?
129 Default: True
130 Options: True|False
132 This determines whether the fluxdensity set in
133 the model is calculated on a per channel
134 basis. If False then it only one fluxdensity
135 value is calculated per spw. (Either way, all
136 channels in spw are modified.) It is effectively
137 True if fluxdensity[0] > 0.0.
138 standard Flux density standard, used if fluxdensity[0] less than 0.0
139 Default: 'Perley-Butler 2017'
140 Options: 'Baars', 'Perley 90', 'Perley-Taylor
141 95', 'Perley-Taylor 99', 'Perley-Butler 2010',
142 'Perley-Butler 2013', 'Perley-Butler 2017',
143 'Scaife-Heald 2012', 'Stevens-Reynolds 2016',
144 'Butler-JPL-Horizons 2010', 'Butler-JPL-Horizons
145 2012', 'manual' 'fluxscale'
147 All but the last four options are for
148 extragalactic calibrators. The two 'Butler-JPL'
149 standards are for Solar System objects. Note that
150 Scaife-Heald 2012 is for the low frequencies
151 (mostly valid for the frequency range,
152 30-300MHz).
154 Flux density calculation with Solar System
155 objects depends on ephemerides. The setjy task
156 looks for the data in
157 os.getenv('CASAPATH').split()[0] +
158 '/data/ephemerides/JPL-Horizons'. If no ephemeris
159 for the right object at the right time is
160 present, the calculation will fail. Ask the
161 helpdesk to make an ephemeris.
163 For more information on individual calibrators,
164 see CASA Docs (https://casa.nrao.edu/casadocs/)
165 model Model image (I only) for setting the model visibilities.
166 Subparameter of standard="Perley-Butler 2010",
167 "Perley-Butler 2013", and "Perley-Butler 2017"
168 Default: '' (do not use a model image)
170 The model can be a cube, and its channels do not
171 have to exactly match those of vis. It is
172 recommended to use model for sources that are
173 resolved by the observation, but the
174 Butler-JPL-Horizons standard supplies a basic
175 model of what several Solar System objects look
176 like. Each field must be done separately when
177 using a model image.
179 Both the amplitude and phase are calculated. At
180 the AOC or CV, the models are located in
181 casa['dirs']['data'] + '/nrao/VLA/CalModels/',
182 e.g. /usr/lib/casapy/data/nrao/VLA/CalModels/3C286_L.im
183 lib64
185 If model does not start with '/', setjy will look
186 for a match in '.', './CalModels', and any
187 CalModels directories within the
188 casa['dirs']['data'] tree (excluding certain
189 branches).
191 Note that model should be deconvolved, i.e. a set
192 of clean components instead of an image that has
193 been convolved with a clean beam.
194 listmodels List the available models for VLA calibrators or Tb
195 models for Solar System objects
196 Subparameter of standard="Perley-Butler 2010",
197 "Perley-Butler 2013", and "Perley-Butler 2017"
198 Default: False
199 Options: False|True
201 If True, do nothing but list candidates for model
202 (for extragalactic calibrators) that are present
203 on the system. It looks for *.im* *.mod* in
204 . including its sub-directories but skipping any
205 directory name start with ".", CalModels, and
206 CalModels directories in the casa['dirs']['data']
207 tree. It does not check whether they are
208 appropriate for the MS! If
209 standard='Butler-JPL-Horizons 2012', Tb models
210 (frequency-dependend brightness temperature
211 models) for Solar System objects used in the
212 standard. For standard='Butler-JPL-Horizons
213 2010', the recognized Solar System objects are
214 listed.
215 fluxdensity Specified flux density in Jy [I,Q,U,V]
216 Subparameter of standard="manual"
217 Default: -1 (uses [1,0,0,0] flux density for
218 unrecognized sources, and standard flux densities
219 for ones recognized by the default standard
220 Perley-Butler 2010).
222 Only one flux density can be specified at a
223 time. The phases are set to zero.
224 setjy will try to use the standard if fluxdensity
225 is not positive.
227 Examples:
228 fluxdensity=-1 will use the default standard
229 for recognized calibrators (like 3C286, 3C147
230 and 3C48) and insert 1.0 for selected fields
231 with unrecognized sources.
232 field = '1'; fluxdensity=[3.2,0,0,0] will put
233 in a flux density of I=3.2 for field='1'
235 At present (June 2000), this is the only method
236 to insert apolarized flux density model.
238 Example: fluxdensity=[2.63,0.21,-0.33,0.02]
239 will put in I,Q,U,V flux densities of
240 2.63,0.21,-0.33, and 0.02, respectively, in
241 the model column.
242 spix Spectral index for I flux density
243 Subparameter of standard="manual"
244 Default: [] =>0.0 (no effect)
245 Options: a float or a list of float values
247 S = fluxdensity *
248 (freq/reffreq)**(spix[0]+spix[1]*log(freq/reffreq)+..)
250 Only used if fluxdensity is being used.
251 IMPORTANT: If fluxdensity is positive, and spix
252 is nonzero, then reffreq must be set too!
254 It is applied in the same way to all
255 polarizations, and does not account for Faraday
256 rotation or depolarization.
258 Example: [-0.7, -0.15] for alpha and a curvature term
259 reffreq Reference frequency for spix
260 Subparameter of standard="manual"
261 Default: '1GHz' (this is only here to prevent
262 division by 0!)
264 Given with a unit with an optional frequency
265 frame (if the frame is not given, LSRK is
266 assumed). There should be no space between the
267 value and the unit (e.g. '100.0GHz' or 'TOPO
268 100.0GHz' are correct but with '100.0 GHz' you
269 will see a warning message that it will be
270 defaulted to LSRK).
272 Example: '86.0GHz', 'TOPO 86.0GHz', '4.65e9Hz'
274 NOTE: If the flux density is being scaled by
275 spectral index, then reffreq must be set to
276 whatever reference frequency is correct for the
277 given fluxdensity and spix. It cannot be
278 determined from vis. On the other hand, if spix
279 is 0, then any positive frequency can be used
280 (and ignored).
281 polindex Coefficients of the frequency-dependent linear
282 polarization index (polarization fraction)
283 Subparameter of standard="manual"
284 Default: []
286 Expressed as pol. index = sqrt(Q^2+U^2)/I = c0 +
287 c1*((freq-reffreq)/reffreq) +
288 c2*((freq-reffreq)/reffreq)^2 + .. When Q and U
289 flux densities are given fluxdensity, c0 is
290 determined from these flux densities and the
291 entry for c0 in polindex is ignored. Or Q and U
292 flux densities in fluxdensity can be set to 0.0
293 and then polindex[0] and polangle[0] are used to
294 determine Q and U at reffreq.
296 Example: [0.2, -0.01] (= [c0,c1])
297 polangle Coefficients of the frequency-dependent linear
298 polarization angle (in radians)
299 Subparameter of standard="manual"
300 Default: []
302 Expressed as pol. angle = 0.5*arctan(U/Q) = d0 +
303 d1*((freq-reffreq)/reffreq) +
304 d2*((freq-reffreq)/reffreq)^2 + .. When Q and U
305 flux densities are given in fluxdensity, d0 is
306 determined from these flux densities and the
307 entry for d0 in polangle is ignored. Or Q and U
308 flux densities in fluxdensity can be set to 0.0
309 and then polindex[0] and polangle[0] are used to
310 determine Q and U at reffreq. Here polangle
311 parameters are assumed to represent the intrinsic
312 polarization angle.
314 Example: [0.57, 0.2] (=[d0,d1])
315 rotmeas Rotation measure (in rad/m^2)
316 Subparameter of standard="manual"
317 Default: 0.0
319 Note on the use of polindex, polangle and rotmeas
320 When the frequnecy-dependent polindex and
321 polangle are used, be sure to include all the
322 coefficients of both polindex and polangle to
323 describe frequency depencency. Otherwise
324 frequency-dependent Q and U flux densities are
325 not calculated correctly. If rotmeas is given,
326 the calculated Q and U flux densities are then
327 corrected for the Faraday rotation.
328 fluxdict Output dictionary from fluxscale
329 Subparameter of standard="fluxscale"
331 Using the flexibly results, the flux density,
332 spectral index, and reference frequency are
333 extracted and set to fluxdensity, spix, and
334 reffreq parameters, respectively. The field and
335 spw selections can be used to specify subset of
336 the fluxdict to be used to set the model. If they
337 are left as default (field="", spw="") all fields
338 and/or spws in the fluxdict (but those spws with
339 fluxd=-1 will be skipped) are used.
340 useephemdir Use directions in the ephemeris table for the solar
341 system object?
342 Subparameter of standard="Butler-JPL-Horizons
343 2012",
344 Default: False
345 Options: False|True
346 interpolation Method to be used to interpolate in time for the time
347 variable sources (3C48,3C138,3C147).
348 Subparameter of standard="Perley-Butler 2013",
349 and "Perley-Butler 2017"
350 Default: 'nearest'
351 Options: 'nearest|linear|cubic|spline'
353 This parameter is ignored for other non-variable
354 sources in the standard.
355 usescratch Will create if necessary and use the MODEL_DATA
356 Default: True
357 Options: True|False
359 * If True: the model visibility will be evaluated
360 and saved on disk in the MODEL_DATA column.
361 This will increase your ms in size by a factor
362 of 1.5 (w.r.t. the case where you only have
363 the DATA and the CORRECTED_DATA column). Use
364 True if you need to interact with the
365 MODEL_DATA in python, say. Also, use True if
366 you need finer than field and spw selections
367 using scans/time (and when use with intent
368 selection, please see WARNING section in the
369 intent parameter description).
370 * If False: 'virtual' model is created. The model
371 information is saved either in the SOURCE_MODEL
372 column in the SOURCE table (if one exists) or
373 in the keyword of the main table in the MS, and
374 model visibilities are evaluated on the fly
375 when calculating calibration or plotting in
376 plotms.
378 By running usescratch=T, it will remove the
379 existing virtual model from previous
380 runs. usescratch=F will not remove the existing
381 MODEL_DATA but in subsequent process the virtual
382 model with matching field and spw combination
383 will be used if it exists regardless of the
384 presence of the MODEL_DATA column.
386 NOTE: for usescratch=False, timerange, scan, and
387 observation are ignored (i.e. time-specific
388 virtual model is not possible.).
390 VERY IMPORTANT: The current implementation of
391 time-dependent models (e.g. ephemerides sources)
392 within setjy is incompatible with the use of the
393 virtual model column. Please use ephemerides source
394 models only with usescratch=True
395 ismms to be used internally for MMS
397 --------- examples -----------------------------------------------------------
400 FOR MORE INFORMATION, SEE THE TASK PAGES OF SETJY IN CASA DOCS:
401 https://casa.nrao.edu/casadocs/
404 """
406 _info_group_ = """imaging, calibration"""
407 _info_desc_ = """Fills the model column with the visibilities of a calibrator"""
409 def __call__( self, vis='', field='', spw='', selectdata=False, timerange='', scan='', intent='', observation='', scalebychan=True, standard='Perley-Butler 2017', model='', listmodels=False, fluxdensity=int(-1), spix=float(0.0), reffreq='1GHz', polindex=[ ], polangle=[ ], rotmeas=float(0.0), fluxdict={ }, useephemdir=False, interpolation='nearest', usescratch=True, ismms=False ):
410 schema = {'vis': {'type': 'cStr', 'coerce': _coerce.to_str}, 'field': {'type': 'cStr', 'coerce': _coerce.to_str}, 'spw': {'type': 'cStr', 'coerce': _coerce.to_str}, 'selectdata': {'type': 'cBool'}, 'timerange': {'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]}]}, 'intent': {'type': 'cStr', 'coerce': _coerce.to_str}, 'observation': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cInt'}]}, 'scalebychan': {'type': 'cBool'}, 'standard': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'Perley-Taylor 95', 'Butler-JPL-Horizons 2010', 'Perley-Butler 2010', 'Stevens-Reynolds 2016', 'Perley-Taylor 99', 'Perley-Butler 2013', 'Perley 90', 'Scaife-Heald 2012', 'manual', 'Butler-JPL-Horizons 2012', 'Perley-Butler 2017', 'fluxscale', 'Baars' ]}, 'model': {'type': 'cStr', 'coerce': _coerce.to_str}, 'listmodels': {'type': 'cBool'}, 'fluxdensity': {'anyof': [{'type': 'cInt'}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}]}, 'spix': {'anyof': [{'type': 'cFloat', 'coerce': _coerce.to_float}, {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}]}, 'reffreq': {'type': 'cStr', 'coerce': _coerce.to_str}, 'polindex': {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}, 'polangle': {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}, 'rotmeas': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'fluxdict': {'type': 'cDict'}, 'useephemdir': {'type': 'cBool'}, 'interpolation': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'nearest', 'linear', 'spline', '', 'cubic' ]}, 'usescratch': {'type': 'cBool'}, 'ismms': {'type': 'cBool'}}
411 doc = {'vis': vis, 'field': field, 'spw': spw, 'selectdata': selectdata, 'timerange': timerange, 'scan': scan, 'intent': intent, 'observation': observation, 'scalebychan': scalebychan, 'standard': standard, 'model': model, 'listmodels': listmodels, 'fluxdensity': fluxdensity, 'spix': spix, 'reffreq': reffreq, 'polindex': polindex, 'polangle': polangle, 'rotmeas': rotmeas, 'fluxdict': fluxdict, 'useephemdir': useephemdir, 'interpolation': interpolation, 'usescratch': usescratch, 'ismms': ismms}
412 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
413 _logging_state_ = _start_log( 'setjy', [ 'vis=' + repr(_pc.document['vis']), 'field=' + repr(_pc.document['field']), 'spw=' + repr(_pc.document['spw']), 'selectdata=' + repr(_pc.document['selectdata']), 'timerange=' + repr(_pc.document['timerange']), 'scan=' + repr(_pc.document['scan']), 'intent=' + repr(_pc.document['intent']), 'observation=' + repr(_pc.document['observation']), 'scalebychan=' + repr(_pc.document['scalebychan']), 'standard=' + repr(_pc.document['standard']), 'model=' + repr(_pc.document['model']), 'listmodels=' + repr(_pc.document['listmodels']), 'fluxdensity=' + repr(_pc.document['fluxdensity']), 'spix=' + repr(_pc.document['spix']), 'reffreq=' + repr(_pc.document['reffreq']), 'polindex=' + repr(_pc.document['polindex']), 'polangle=' + repr(_pc.document['polangle']), 'rotmeas=' + repr(_pc.document['rotmeas']), 'fluxdict=' + repr(_pc.document['fluxdict']), 'useephemdir=' + repr(_pc.document['useephemdir']), 'interpolation=' + repr(_pc.document['interpolation']), 'usescratch=' + repr(_pc.document['usescratch']), 'ismms=' + repr(_pc.document['ismms']) ] )
414 task_result = None
415 try:
416 task_result = _setjy_t( _pc.document['vis'], _pc.document['field'], _pc.document['spw'], _pc.document['selectdata'], _pc.document['timerange'], _pc.document['scan'], _pc.document['intent'], _pc.document['observation'], _pc.document['scalebychan'], _pc.document['standard'], _pc.document['model'], _pc.document['listmodels'], _pc.document['fluxdensity'], _pc.document['spix'], _pc.document['reffreq'], _pc.document['polindex'], _pc.document['polangle'], _pc.document['rotmeas'], _pc.document['fluxdict'], _pc.document['useephemdir'], _pc.document['interpolation'], _pc.document['usescratch'], _pc.document['ismms'] )
417 except Exception as exc:
418 _except_log('setjy', exc)
419 raise
420 finally:
421 task_result = _end_log( _logging_state_, 'setjy', task_result )
422 return task_result
424setjy = _setjy( )