simanalyze – image and analyze measurement sets created with simobserve – simulation task

Description

This task is for imaging and analyzing MeasurementSets simulated with simobserve or simalma. It consists of two main steps, controlled by the image and analyze parameters. ——————————- Output produced: (not all will always exist, depending on input parameters) To support different runs with different arrays, the names have the configuration name from antennalist appended. ——————————- * tclean outputs: [project].[cfg].image = synthesized image [project].[cfg].residual = residual image after cleaning [project].[cfg].pb = primary beam [project].[cfg].image.pbcor = synthesized image corrected for primary beam attenuation [project].[cfg].psf = synthesized (dirty) beam calculated from weighted uv distribution [project].[cfg].mask = clean mask [project].[cfg].model = sky brightness model [project].[cfg].sumwt = single pixel image containing sum-of-weights [project].[cfg].weight = Fourier transform of gridder weights, or un-normalized sum of PB-square (for all pointings) [project].[cfg].tclean.last = parameter file of what parameters were used in the tclean task; also generated by simutil even when dryrun=True

simulator outputs:

[project].[cfg].skymodel.flat.regrid.conv = input sky regridded to match the output image, and convolved with the output clean beam [project].[cfg].fidelity = fidelity image [project].[cfg].image.png = diagnostic figure of clean image and residual [project].[cfg].analysis.png = diagnostic figure of difference and fidelity [project].[cfg].diff = difference image between flattened convolved model and flattened output [project].[cfg].image.flat = 2D integrated intensity image, not corrected for primary beam; see simutil.modifymodel [project].[cfg].simanalyze.last = saved input parameters for simanalyze task, available in CASAshell ——————————-

“project” needs to be the directory of results generated by running simobserve or simalma. In particular $project/$project.skymodel will be required in order to compare output and input images.

NOTE: simanalyze was designed to be used after one or more runs of simobserve, and as such it assumes it will be able to find a sky model image called $project/$project.skymodel, .newmodel, or .compskymodel in the $project/ subdirectory. If the simulated MS has been created by means other than simply calling simobserve, the user may have to copy their sky model image into the $project subdirectory and call it “$project.skymodel”.

interactive clean or use of more parameters than the subset visible here are available by simply running the tclean task directly, then using simanalyze in the mode image=False (see below).

Sometimes it is preferable to grid the single dish MS using the sdimaging task for more control. In that case one can input the resulting single dish imaging under “featherimage”, only put interferometric MSs in “vis”, and simanalyze will clean the interferometric and feather with your “featherimage”.

uses Cotton-Schwab clean for single fields and Mosaic gridding for multiple fields (with Clark PSF calculation in minor cycles).

Parameters

Title
Parameter	Default	Description
project	`'sim'`	root prefix for output file names
image	`True`	(re)image $project.*.ms to $project.image
imagename	`'default'`	simulation output image to analyze
skymodel	`''`	skymodel image to analyze
vis	`'default'`	Measurement Set(s) to image
modelimage	`''`	image to use as clean prior
imsize	`numpy.array( [ int(0),int(0) ] )`	output image size in pixel units
imdirection	`''`	set output image direction
cell	`''`	cell size with units
interactive	`False`	call tclean in interactive mode
niter	`int(0)`	maximum number of iterations
threshold	`'0.1mJy'`	target flux level and units
weighting	`'natural'`	control image weighting method
mask	`numpy.array( [ ] )`	Cleanbox(es), mask image(s), region(s), or a level
outertaper	`numpy.array( [ ] )`	uv-taper on outer baselines in uv-plane
pbcor	`True`	correct synthesis images for primary beam response?
stokes	`'I'`	Stokes parameterss to image
featherimage	`''`	image to feather with new image
analyze	`False`	create analytical images
showuv	`True`	display uv coverage
showpsf	`True`	display synthesized beam
showmodel	`True`	display sky model at original resolution
showconvolved	`False`	display sky model convolved with output clean beam
showclean	`True`	display the synthesized image
showresidual	`False`	display the clean residual image
showdifference	`True`	display difference between cleaned output and convolved model input
showfidelity	`True`	display fidelity image
graphics	`'both'`	where to display graphics at each stage
verbose	`False`	report task activity
overwrite	`True`	overwrite files starting with $project
dryrun	`False`	only print information
logfile	`''`	user-defined log file

Parameter Explanations

project

'sim'

root prefix for input and output file names. This must be the directory of results generated by running simobserve or simalma. In particular $project/$project.skymodel will be required in order to compare output and input images.

image

True

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).

imagename

'default'

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

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.

vis

'default'

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”.

modelimage

''

Sometimes it is preferable to use a low resolution (single dish or synthesis) image as a prior 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 via the simutil method imtclean. Note that this is separate from the functionality controlled by the featherimage parameter. Also note that this is not the original skymodel that was used in simobserve or simalma. It is recommended to leave this blank unless the user is familiar with using a prior in clean deconvolution. Also note that the modelimage will not be used if the MS to be imaged is total power.

imsize

numpy.array( [ int(0),int(0) ] )

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.

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.

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.

interactive

False

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.

niter

int(0)

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.

threshold

'0.1mJy'

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.

weighting

'natural'

Set the weighting scheme to apply to visibilities during image reconstruction. If set to briggs, will use the tclean default robust parameter (0.5)

mask

numpy.array( [ ] )

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]

outertaper

numpy.array( [ ] )

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.

pbcor

True

Controls whether primary beam correction is applied in the call to task tclean.

stokes

'I'

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.

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.

analyze

False

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.

showuv

True

Displays a plot of the simulated uv coverage

showpsf

True

Displays synthesized (dirty) beam. Ignored in single dish simulation.

showmodel

True

Displays the sky model at original resolution of input image.

showconvolved

False

Displays the sky model convolved with output clean beam.

showclean

True

Displays the synthesized image produced by the call to task tclean.

showresidual

False

Displays the residual image produced by the call to task tclean. Ignored in single dish simulations.

showdifference

True

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.

showfidelity

True

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) ]

graphics

'both'

Controls where graphics are displayed. Options are screen, file, both, or none.

verbose

False

Controls task activity is reported in the log.

overwrite

True

Controls whether the task will overwrite existing files starting with $project name.

dryrun

False

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.

logfile

''

Allows for a user-defined log file naming convention if the verbose parameter is set to True.