Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/simanalyze.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 simanalyze.xml ################
2##################### 9b3ad0257c8bf3958fa047ff972bca10 ##############################
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_simanalyze import simanalyze as _simanalyze_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 _simanalyze:
15 """
16 simanalyze ---- image and analyze measurement sets created with simobserve
19 This task is for imaging and analyzing MeasurementSets simulated with simobserve or simalma.
20 It consists of two main steps, controlled by the image and analyze parameters.
21 -------------------------------
22 Output produced: (not all will always exist, depending on input parameters)
23 To support different runs with different arrays, the names have the
24 configuration name from antennalist appended.
25 -------------------------------
26 **tclean outputs:**
27 [project].[cfg].image = synthesized image
28 [project].[cfg].residual = residual image after cleaning
29 [project].[cfg].pb = primary beam
30 [project].[cfg].image.pbcor = synthesized image corrected for primary beam attenuation
31 [project].[cfg].psf = synthesized (dirty) beam calculated from weighted uv distribution
32 [project].[cfg].mask = clean mask
33 [project].[cfg].model = sky brightness model
34 [project].[cfg].sumwt = single pixel image containing sum-of-weights
35 [project].[cfg].weight = Fourier transform of gridder weights, or un-normalized sum of PB-square (for all pointings)
36 [project].[cfg].tclean.last = parameter file of what parameters were used in the tclean task; also generated by simutil even when dryrun=True
38 **simulator outputs:**
39 [project].[cfg].skymodel.flat.regrid.conv = input sky regridded to match the output image, and convolved with the output clean beam
40 [project].[cfg].fidelity = fidelity image
41 [project].[cfg].image.png = diagnostic figure of clean image and residual
42 [project].[cfg].analysis.png = diagnostic figure of difference and fidelity
43 [project].[cfg].diff = difference image between flattened convolved model and flattened output
44 [project].[cfg].image.flat = 2D integrated intensity image, not corrected for primary beam; see simutil.modifymodel
45 [project].[cfg].simanalyze.last = saved input parameters for simanalyze task, available in CASAshell
46 -------------------------------
48 "project" needs to be the directory of results generated by running
49 simobserve or simalma. In particular $project/$project.skymodel
50 will be required in order to compare output and input images.
52 NOTE: simanalyze was designed to be used after one or more runs of
53 simobserve, and as such it assumes it will be able to find a
54 sky model image called $project/$project.skymodel, .newmodel, or
55 .compskymodel in the $project/ subdirectory. If the simulated
56 MS has been created by means other than simply calling simobserve,
57 the user may have to copy their sky model image into the $project
58 subdirectory and call it "$project.skymodel".
60 interactive clean or use of more parameters than the subset
61 visible here are available by simply running the tclean task directly,
62 then using simanalyze in the mode image=False (see below).
64 Sometimes it is preferable to grid the single dish MS using the
65 sdimaging task for more control. In that case one can input
66 the resulting single dish imaging under "featherimage", only
67 put interferometric MSs in "vis", and simanalyze will clean the
68 interferometric and feather with your "featherimage".
70 uses Cotton-Schwab clean for single fields and Mosaic gridding
71 for multiple fields (with Clark PSF calculation in minor cycles).
74 --------- parameter descriptions ---------------------------------------------
76 project root prefix for input and output file names.
77 This must be the directory of results generated by running
78 simobserve or simalma. In particular $project/$project.skymodel
79 will be required in order to compare output and input images.
80 image Controls whether tclean is called to image the MeasurementSet data. If true, input one or more simulated MSs using the vis parameter. These can include a total power MS. This task will grid any total power MS, invert and deconvolve any interferometric MS(s) (using the simutil method imtclean), and feather the results. If this parameter is set to False (e.g., if the user has created a synthesized image themselves or simanalyze has previously been run with image=True) the user should provide that image as input to the imagename parameter. This task will then attempt to find an appropriate skymodel image (such as the optionally rescaled \*.skymodel produced by simobserve or simalma and used to create the MS).
81 imagename Name of image to image/analyze, expected to be of the same form as those generated by simobserve. Defaults to the first file found with the name $project/\*.image
82 skymodel Name of a specific .skymodel image created by simobserve or simalma and used by one of those tasks to create a MS. If unspecified, will try to find one similar to your specified output image name.
83 vis Name of the Measurement Set(s) to image, specified as a string or string containing a comma separating the names. If set to "default", will attempt to find and image all MeasurementSets (interferometric and single dish) in the project directory. Note that if you created MeasurementSets using simobserve, the names will include the antenna configuration. Example of a single MS: vis="mysim.alma.out03.ms". Example of multiple MSs: vis="mysim.alma.out03.ms,mysim.aca.tp.ms". Example of using the $project syntax: vis="$project.noisy.ms,$project.noisy.sd.ms".
84 modelimage Sometimes it is preferable to use a low resolution (single dish or synthesis) image as a starting model during clean deconvolution of a higher resolution interferometric MS. That is accomplished by specifying the low-resolution image as input to this parameter, and the MS to be deconvolved as input to the vis parameter. This parameter is passed to the startmodel parameter of tclean via the simutil method imtclean. Note that this is separate from the functionality controlled by the featherimage parameter and that it is not necessarily the original skymodel that was used in simobserve or simalma. Also note that the modelimage will not be used if the MS to be imaged is total power.
85 imsize A list of integers corresponding to the number of pixels in (x,y) dimensions of output image. If 0, will attempt to match model image.
86 imdirection A string corresponding to a direction to adopt as phase center, including epoch, right ascension, and declination. If unset, will adopt center on the model.
87 cell Specify the cell size with units, e.g., "10arcsec". If left unset (an empty string), the model cell size will be used. This is the default setting.
88 interactive Controls how the simutil method imtclean will call the tclean task. If this parameter is set to True, make sure to set the parameter niter to a value >0.
89 niter Controls the value of the niter parameter in tclean call, and thus the maximum number of iterations per minor cycle. Set to 0 to produce a dirty image. Can also be modified through the viewer GUI via the interactive parameter.
90 threshold Set the quantity corresponding to the target flux level at which to stop cleaning. This value is passed to tclean via the simutil method imtclean.
91 weighting Set the weighting scheme to apply to visibilities during image reconstruction. If set to briggs, will use the tclean default robust parameter (0.5)
92 mask Accepts a list of cleanbox(es), mask image file name(s), region(s), and/or a primary beam coverage level. Input to this parameter will specify areas to be searched for clean components. tclean tends to perform better and is less likely to diverge if the component placement is limited by a mask to where real emission is expected. See the tclean task documentation for more information about masking. Example of a pixel range mask: mask=[110,110,150,145]
93 outertaper Accepts a list of strings in the form of a quantity that sets an other threshold on baselines in the uv-plane. Usually used to achieve a lower effective angular resolution and recover more extended emission in reconstructed image. If left unset via empty list (the default) no outer taper will be applied.
94 pbcor Controls whether primary beam correction is applied in the call to task tclean.
95 stokes Stokes parameters to include in the call to tclean via the simutil method imtclean. Note that forming Stokes Q and U images requires the presence of cross-hand polarizations (e.g., RL and LR for circularly polarized systems such as the VLA) in the input data. Stokes V requires both parallel hands (RR and LL) for circularly-polarized systems or the cross-hands (XY and YX) for linearly polarized systems such as ALMA and ATCA.
96 featherimage String corresponding to the name of an image (e.g., total power data) to feather with the interferometric synthesis image. Sometimes it is preferable to grid the single dish MS using the sdimaging task for more control. In that case, the user can input the resulting single dish imaging under featherimage, only pass interferometric data as input to the vis parameter, and this task will clean the interferometric and feather with the featherimage.
97 analyze Used to create an image of the difference between the input skymodel and the simulated output image (whether that output image is being generated in the same call to simanalyze, with image=True, or has already been generated, and simanalyze is being called with image=False). If True, only the first 6 selected subparameter outputs will be displayed.
98 showuv Displays a plot of the simulated uv coverage
99 showpsf Displays synthesized (dirty) beam. Ignored in single dish simulation.
100 showmodel Displays the sky model at original resolution of input image.
101 showconvolved Displays the sky model convolved with output clean beam.
102 showclean Displays the synthesized image produced by the call to task tclean.
103 showresidual Displays the residual image produced by the call to task tclean. Ignored in single dish simulations.
104 showdifference Displays a difference image between cleaned image output by the tclean call, and input model sky image convolved with synthesized beam determined by output of tclean call.
105 showfidelity Display a fidelity image. Note that the RMS is calculated in the lower quarter of the image. This is likely not the best choice, so you are encouraged to measure RMS yourself in an off-source region. Fidelity = abs(input) / max[ abs(input-output), 0.7\*rms(output) ]
106 graphics Controls where graphics are displayed. Options are screen, file, both, or none.
107 verbose Controls task activity is reported in the log.
108 overwrite Controls whether the task will overwrite existing files starting with $project name.
109 dryrun Experimental feature for interfermetric data only. Controls whether information pertaining to the tclean call and analysis will be recorded and written to files for inspection and adaption.
110 logfile Allows for a user-defined log file naming convention if the verbose parameter is set to True.
111 [1;42mRETURNS[1;m void
113 --------- examples -----------------------------------------------------------
116 For more information, see the task pages of simobserve in CASA Docs:
118 https://casa.nrao.edu/casadocs/
120 Please see http://casaguides.nrao.edu, and contact the CASA helpdesk
121 with questions.
125 """
127 _info_group_ = """simulation"""
128 _info_desc_ = """image and analyze measurement sets created with simobserve"""
130 def __call__( self, project='sim', image=True, imagename='default', skymodel='', vis='default', modelimage='', imsize=[ int(0),int(0) ], imdirection='', cell='', interactive=False, niter=int(0), threshold='0.1mJy', weighting='natural', mask=[ ], outertaper=[ ], pbcor=True, stokes='I', featherimage='', analyze=False, showuv=True, showpsf=True, showmodel=True, showconvolved=False, showclean=True, showresidual=False, showdifference=True, showfidelity=True, graphics='both', verbose=False, overwrite=True, dryrun=False, logfile='' ):
131 schema = {'project': {'type': 'cStr', 'coerce': _coerce.to_str}, 'image': {'type': 'cBool'}, 'imagename': {'type': 'cStr', 'coerce': _coerce.to_str}, 'skymodel': {'type': 'cStr', 'coerce': _coerce.to_str}, 'vis': {'type': 'cStr', 'coerce': _coerce.to_str}, 'modelimage': {'type': 'cStr', 'coerce': _coerce.to_str}, 'imsize': {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, 'imdirection': {'type': 'cStr', 'coerce': _coerce.to_str}, 'cell': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'interactive': {'type': 'cBool'}, 'niter': {'type': 'cInt'}, 'threshold': {'type': 'cStr', 'coerce': _coerce.to_str}, 'weighting': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'natural', 'uniform', 'briggs' ]}, 'mask': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'outertaper': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'pbcor': {'type': 'cBool'}, 'stokes': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'I', 'IQUV', 'RRLL', 'QU', 'YY', 'RR', 'IV', 'XX', 'XXYY', 'LL' ]}, 'featherimage': {'type': 'cStr', 'coerce': _coerce.to_str}, 'analyze': {'type': 'cBool'}, 'showuv': {'type': 'cBool'}, 'showpsf': {'type': 'cBool'}, 'showmodel': {'type': 'cBool'}, 'showconvolved': {'type': 'cBool'}, 'showclean': {'type': 'cBool'}, 'showresidual': {'type': 'cBool'}, 'showdifference': {'type': 'cBool'}, 'showfidelity': {'type': 'cBool'}, 'graphics': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'none', 'file', 'both', 'screen', '' ]}, 'verbose': {'type': 'cBool'}, 'overwrite': {'type': 'cBool'}, 'dryrun': {'type': 'cBool'}, 'logfile': {'type': 'cStr', 'coerce': _coerce.to_str}}
132 doc = {'project': project, 'image': image, 'imagename': imagename, 'skymodel': skymodel, 'vis': vis, 'modelimage': modelimage, 'imsize': imsize, 'imdirection': imdirection, 'cell': cell, 'interactive': interactive, 'niter': niter, 'threshold': threshold, 'weighting': weighting, 'mask': mask, 'outertaper': outertaper, 'pbcor': pbcor, 'stokes': stokes, 'featherimage': featherimage, 'analyze': analyze, 'showuv': showuv, 'showpsf': showpsf, 'showmodel': showmodel, 'showconvolved': showconvolved, 'showclean': showclean, 'showresidual': showresidual, 'showdifference': showdifference, 'showfidelity': showfidelity, 'graphics': graphics, 'verbose': verbose, 'overwrite': overwrite, 'dryrun': dryrun, 'logfile': logfile}
133 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
134 _logging_state_ = _start_log( 'simanalyze', [ 'project=' + repr(_pc.document['project']), 'image=' + repr(_pc.document['image']), 'imagename=' + repr(_pc.document['imagename']), 'skymodel=' + repr(_pc.document['skymodel']), 'vis=' + repr(_pc.document['vis']), 'modelimage=' + repr(_pc.document['modelimage']), 'imsize=' + repr(_pc.document['imsize']), 'imdirection=' + repr(_pc.document['imdirection']), 'cell=' + repr(_pc.document['cell']), 'interactive=' + repr(_pc.document['interactive']), 'niter=' + repr(_pc.document['niter']), 'threshold=' + repr(_pc.document['threshold']), 'weighting=' + repr(_pc.document['weighting']), 'mask=' + repr(_pc.document['mask']), 'outertaper=' + repr(_pc.document['outertaper']), 'pbcor=' + repr(_pc.document['pbcor']), 'stokes=' + repr(_pc.document['stokes']), 'featherimage=' + repr(_pc.document['featherimage']), 'analyze=' + repr(_pc.document['analyze']), 'showuv=' + repr(_pc.document['showuv']), 'showpsf=' + repr(_pc.document['showpsf']), 'showmodel=' + repr(_pc.document['showmodel']), 'showconvolved=' + repr(_pc.document['showconvolved']), 'showclean=' + repr(_pc.document['showclean']), 'showresidual=' + repr(_pc.document['showresidual']), 'showdifference=' + repr(_pc.document['showdifference']), 'showfidelity=' + repr(_pc.document['showfidelity']), 'graphics=' + repr(_pc.document['graphics']), 'verbose=' + repr(_pc.document['verbose']), 'overwrite=' + repr(_pc.document['overwrite']), 'dryrun=' + repr(_pc.document['dryrun']), 'logfile=' + repr(_pc.document['logfile']) ] )
135 task_result = None
136 try:
137 task_result = _simanalyze_t( _pc.document['project'], _pc.document['image'], _pc.document['imagename'], _pc.document['skymodel'], _pc.document['vis'], _pc.document['modelimage'], _pc.document['imsize'], _pc.document['imdirection'], _pc.document['cell'], _pc.document['interactive'], _pc.document['niter'], _pc.document['threshold'], _pc.document['weighting'], _pc.document['mask'], _pc.document['outertaper'], _pc.document['pbcor'], _pc.document['stokes'], _pc.document['featherimage'], _pc.document['analyze'], _pc.document['showuv'], _pc.document['showpsf'], _pc.document['showmodel'], _pc.document['showconvolved'], _pc.document['showclean'], _pc.document['showresidual'], _pc.document['showdifference'], _pc.document['showfidelity'], _pc.document['graphics'], _pc.document['verbose'], _pc.document['overwrite'], _pc.document['dryrun'], _pc.document['logfile'] )
138 except Exception as exc:
139 _except_log('simanalyze', exc)
140 raise
141 finally:
142 task_result = _end_log( _logging_state_, 'simanalyze', task_result )
143 return task_result
145simanalyze = _simanalyze( )