Difference between revisions of "Simulation Guide for New Users (CASA 3.3)"

From CASA Guides
Jump to: navigation, search
m (moved Simdata New Users Guide (CASA 3.3) to Simulation for New Users (CASA 3.3): simdata has become sim_observe and sim_analyze)
 
(66 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{Simulations Intro}}
 
{{Simulations Intro}}
  
''Old version: [[Simdata New Users Guide (CASA 3.2)]].''
+
''This guide is applicable to CASA version 3.3.  For simulation instructions for older versions of CASA see [[Simdata New Users Guide (CASA 3.2)]].''
  
Remember that you need to follow this process: [[Extracting scripts from these tutorials]] to extract a casapy script from this web page.
+
To create a script of the Python code on this page see [[Extracting scripts from these tutorials]].
  
 
==Explanation of the guide==
 
==Explanation of the guide==
  
This guide is intended to be used as an initial walk-through of how to use simdataWe will start with an image similar to something that might be observed with ALMA, and then we will show how to rescale the image and predict how it will look when observed with different antenna configurations.
+
When planning an interferometric observation it is useful to simulate the output of the instrument under a variety of conditionsIn CASA, interferometric observations can be simulated using task <tt>sim_observe</tt> and quickly analyzed using task <tt>sim_analyze</tt>.  This guide will demonstrate how to simulate an ALMA observation using these tasks.  (Task <tt>sim_observe</tt> can also be used to simulate observations with other interferometers, but this currently requires advanced techniques not covered here.)
  
We will assume only a general knowledge of interferometry and no specific knowledge of CASA.
+
We begin with an image similar to something that might be observed with ALMA.  We show how to rescale the image and specify the ALMA antenna configuration.  We produce a simulated set of visibility measurements and then produce an image from the visibility data.  In the process, we also generate useful figures to help us analyze the simulated output. 
 +
 
 +
We will assume throughout only a general knowledge of interferometry and no specific knowledge of CASA.
  
 
==Getting Started==
 
==Getting Started==
  
The two things you need to get started are:
+
The two things you need to get started are
# The image to work with
+
# The image we will work with, and
# The current version of CASA
+
# CASA version 3.3.
  
To get the image, download the Spitzer IRAC 8 micron image of 30 Doradus from the [http://casaguides.nrao.edu/index.php?title=Sim_Inputs Simulation Inputs CASA Guide page].
+
We will use the Spitzer IRAC 8 micron image of 30 Doradus, which you can download from the [http://casaguides.nrao.edu/index.php?title=Sim_Inputs Simulation Inputs CASA Guide page].
  
To install CASA, follow the instructions given [http://casa.nrao.edu/casa_obtaining.shtml here].  This guide was written for CASA version 3.2.
+
To install CASA, follow the instructions given on the [http://casa.nrao.edu/casa_obtaining.shtml Obtaining CASA page].
  
==Using CASA==
+
==CASA Basics==
  
CASA is the post-processing package for ALMA and EVLA and can handle both interferometric and single dish data.  Because simdata is a task within CASA, we start here with a brief introduction to some CASA basics.  To learn much more about CASA, go to the [http://casa.nrao.edu CASA homepage].  Walk-throughs of CASA data reduction for a variety of data sets can be found on the [http://casaguides.nrao.edu casaguides website].
+
CASA is the post-processing package for ALMA and EVLA and can handle both interferometric and single dish data.  Because <tt>sim_observe</tt> and <tt>sim_analyze</tt> are tasks within CASA, we start here with a brief introduction to some CASA basics.  To learn much more about CASA, go to the [http://casa.nrao.edu CASA homepage].  Walk-throughs of CASA data reduction for a variety of data sets can be found on the [http://casaguides.nrao.edu CASA Guides website].
 
 
===Starting CASA===
 
  
 
Once you have installed CASA, you can launch it by typing "casapy" at the prompt or by double-clicking on the icon, depending on your system and preferences.   
 
Once you have installed CASA, you can launch it by typing "casapy" at the prompt or by double-clicking on the icon, depending on your system and preferences.   
  
===Running CASA Tasks===
+
[[Image:Simdata_inp_example.png|thumb| Screen shot of <tt>inp sim_observe</tt>.  Note that default values are shown in black, valid and non-default values are shown in blue, and invalid values are shown in red. Expandable parameters have a grey background.]]
 
 
[[Image:Simdata_inp_example.png|thumb|Screen shot of "inp simdata".  Note that "chicken" is not a valid value for "setpointings", so it is shown in red.  "tsys-atm" is a valid, but not the default, value for "thermalnoise" so it is displayed in blue.  The parameter "thermalnoise", in grey, has been expanded based on the value "tsys-atm".]]
 
  
 
To see a list of all available CASA tasks, at the CASA prompt type
 
To see a list of all available CASA tasks, at the CASA prompt type
  > tasklist
+
  tasklist
  
 
To look at the inputs for an available task, use "inp".  For instance
 
To look at the inputs for an available task, use "inp".  For instance
  > inp simdata
+
  inp sim_observe
Any parameter with a grey background is expandable.  Red text shows an invalid value.  Blue text shows an accepted, but not the default, value.
+
Any parameter with a grey background is expandable.  Black text shows a default value.  Red text shows an invalid value.  Blue text shows a valid value different from the default.
  
 
To get help on a given task, use "help" (to exit from help, hit the "q" key).  For instance
 
To get help on a given task, use "help" (to exit from help, hit the "q" key).  For instance
  > help simdata
+
  help sim_analyze
  
 
To reset a task to its default values, use "default".  For instance
 
To reset a task to its default values, use "default".  For instance
  > default simdata
+
  default sim_observe
  
 
To run a task using the current global values of its input parameters, just type its name at the CASA prompt.  For instance
 
To run a task using the current global values of its input parameters, just type its name at the CASA prompt.  For instance
  > simdata
+
  sim_observe
It's a good idea to double-check these values (i.e., re-run "inp simdata") immediately before running a task.
 
  
==Using Simdata==
+
It's a good idea to double-check these values (i.e., re-run <tt>inp sim_observe</tt>) immediately before running a task.
  
===Getting Your Input Image Into Simdata===
+
==Using <tt>sim_observe</tt>==
  
[[Image:NewUsersGuide.modifymodel.png|thumb|Screen shot of input parameters for "modifymodel"]]
+
The task <tt>sim_observe</tt> uses a model image along with a number of input parameters that define the observational conditions and alter the input model.  The output of <tt>sim_observe</tt> is a visibility measurement set and various diagnostic plots and images.
  
Now tell simdata where to find the model (input) image and how to scale it appropriately for our purposes.  Just to be safe, we'll first restore the default values of simdata and then set the 30 Doradus image as the skymodel ('''Note:''' you might need to include the path to your data set, if you are not currently in the working directory where the data set is).  Setting modifymodel=True tells simdata that we will be modifying the image before simulating an ALMA observation.
+
===Getting Your Input Image Into <tt>sim_observe</tt>===
 +
 
 +
First, we'll tell <tt>sim_observe</tt> where to find the model (input) image and how to scale it appropriately for our purposes.  Just to be safe, we'll begin by restoring the default values of <tt>sim_observe</tt> and then set the 30 Doradus image as the skymodel (Note: you might need to include the path to your model image, if you are not currently in the working directory where the image is).
  
 
<source lang="python">
 
<source lang="python">
#Initialize simdata
+
#In CASA
default simdata
+
default sim_observe
modifymodel = True
 
 
skymodel = '30dor.fits'
 
skymodel = '30dor.fits'
 
</source>
 
</source>
 
We are using a Spitzer 8 micron image of 30 Doradus in this example, and we are going to ask simdata to modify this image in some important ways:
 
# Angular scale
 
# Observed wavelength
 
# Brightness scale
 
  
 
====Angular Scale====
 
====Angular Scale====
If you open the fits image of 30 Doradus in your favorite viewer (e.g. 'viewer' in CASA), you will see that it covers quite a large footprint on the sky, about 10' on a side. We are going to tell simdata to rescale the pixels to shrink the image by roughly a factor of 15 (from  2.3" to 0.15" pixels through the 'incell' parameter) so that the model is approximately 40" on a side.  This rescaled model will fit within a small mosaic of 6 pointings.  Although we do this primarily for convenience in this example, a scientific motivation for this type of rescaling would be to approximate what a super-giant HII region like 30 Doradus would look like if moved from the Large Magellanic Cloud to the distance of M33 or M31.  For the sake of demonstration, we will also change the coordinates of the center of the map (using the 'indirection' parameter). Units are case sensitive, please take care to enter them in verbatim, CASA will throw an error otherwise.
+
If you open the FITS image of 30 Doradus in your favorite viewer (e.g. <tt>viewer</tt> in CASA), you will see that it covers quite a large footprint on the sky, about 10' on a side. We are going to tell <tt>sim_observe</tt> to rescale the pixels to shrink the image by roughly a factor of 15 (from  2.3" to 0.15" pixels through the <tt>incell</tt> parameter) so that the model is approximately 40" on a side.  This rescaled model will fit within a small mosaic of 6 pointings.  Although we do this primarily for convenience in this example, a scientific motivation for this type of rescaling would be to approximate what a super-giant HII region like 30 Doradus would look like if moved from the Large Magellanic Cloud to the distance of M33 or M31.  For the sake of demonstration, we will also change the coordinates of the center of the map (using the <tt>indirection</tt> parameter). Units are case sensitive, so please take care to enter them in verbatimCASA will throw an error otherwise.
  
 
<source lang="python">
 
<source lang="python">
 +
#In CASA
 
incell = '0.15arcsec'
 
incell = '0.15arcsec'
 
indirection = 'J2000 10h00m00 -40d00m00'
 
indirection = 'J2000 10h00m00 -40d00m00'
Line 80: Line 74:
 
====Observed Wavelength====
 
====Observed Wavelength====
  
The model image of 30 Doradus shows the 8 micron continuum emission.  ALMA does not observe at wavelengths this short, so we will tell simdata that this is actually a 230 GHz (1.3 mm) continuum map.  We will also tell simdata that the observations were taken with a 2 GHz bandwidth. Although for this particular example the channel width is not a critical number, it would be very important if we were modifying a spectral cube instead of a continuum image.
+
The model image of 30 Doradus shows 8 micron continuum emission.  ALMA does not observe at wavelengths this short, so we will tell <tt>sim_observe</tt> that this is actually a 230 GHz (1.3 mm) continuum map.  We will also tell <tt>sim_observe</tt> that the observations were taken with a 2-GHz bandwidth. Although for this particular example the channel width is not a critical number, it would be very important if we were modifying a spectral cube instead of a continuum image.
  
 
<source lang="python">
 
<source lang="python">
 +
#In CASA
 
incenter = '230GHz'
 
incenter = '230GHz'
 
inwidth = '2GHz'
 
inwidth = '2GHz'
Line 89: Line 84:
 
====Brightness Scale====
 
====Brightness Scale====
  
The 8 micron emission is probably not a great approximation for the millimeter emission from 30 Doradus.  For a true science case, one would want to calculate what the expected 230 GHz emission would be from an object like this at the distance of about 750 kiloparsec.  For the sake of simplicity, we will rescale the image so that the brightest pixel in the map has a flux density of 0.06 mJy.  This number is chosen such that the extended emission is a factor of a few brighter than the expected noise in a 2 hour observation.  The [https://almascience.nrao.edu/call-for-proposals/sensitivity-calculator ALMA sensitivity calculator] can be used to determine the expected noise in an observation.
+
The 8 micron emission is probably not a great approximation for the millimeter emission from 30 Doradus.  For a true science case, one would want to calculate what the expected 230 GHz emission would be from an object like this at the distance of about 750 kiloparsec.  For the sake of simplicity, we will rescale the image so that the brightest pixel in the map has a flux density of 0.06 mJy.  This number is chosen such that the extended emission is a factor of a few brighter than the expected noise in a 2 hour observation.  The [https://almascience.nrao.edu/call-for-proposals/sensitivity-calculator ALMA sensitivity calculator] can be used to determine the expected noise for an observation.
  
 
<source lang="python">
 
<source lang="python">
 +
#In CASA
 
inbright = '0.06mJy/pixel'
 
inbright = '0.06mJy/pixel'
 
</source>
 
</source>
 +
 +
Remember that you can check your task inputs at any time by typing <tt>inp</tt> at the casa prompt.
  
 
===Defining the Mock Observations===
 
===Defining the Mock Observations===
[[Image:NewUsersGuide3.2.setpointings.predict.png|thumb|Screen shot of input parameters for "setpointings" and "predict"]]
 
  
Now that simdata knows how to interpret the input image, the next step is to define the simulated observations.   
+
Now that <tt>sim_observe</tt> knows how to interpret the input image, the next step is to define the simulated observations.   
  
 
====Pointings and Scan Time====
 
====Pointings and Scan Time====
  
We will first change the parameters within "setpointings"
+
We will first change the parameters within <tt>setpointings</tt>. 
* integration
 
* direction
 
* mapsize
 
* maptype
 
* pointingspacing
 
  
The default value for "integration", 10 seconds, might be appropriate to simulate real observations.  However, simdata will run much faster if the value for "integration" is increased, reducing the number of data points to be generated.  In this demonstration we will set it to 600 seconds.  When simdata is used for scientific purposes it may be best to set "integration" to a large value at first to make sure that simdata runs as expected, and then decrease "integration" to a more realistic time for the final run.  You will get a more accurate simulation with 10 second integrations than with 600 second integrations, especially in Early Science observations with a limited number of baselines.
+
The default value for <tt>integration</tt>, 10 seconds, might be appropriate to simulate real observations.  However, <tt>sim_observe</tt> will run much faster if the value for "integration" is increased, reducing the number of data points to be generated.  In this demonstration we will set it to 600 seconds.  When <tt>sim_observe</tt> is used for scientific purposes it may be best to set <tt>integration</tt> to a large value at first to make sure that <tt>sim_observe</tt> runs as expected, and then decrease <tt>integration</tt> to a more realistic time for the final run.  You will get a more accurate simulation with 10 second integrations than with 600 second integrations, especially in Early Science observations with a limited number of baselines.
  
Note that the integration time is different than the total (on-source) time of the observations.  The integration time, set here, is the averaging time for each data point.  The total time spent on-source is set later on.  Each pair of antennas will generate a number of data points equal to the total observing time divided by the integration time.
+
<source lang="python">
 +
#In CASA
 +
integration = '600s'
 +
</source>
  
We will keep "direction" at the default (blank) value to center the observations on the model coordinates, as given in "indirection" above.
+
Note that the integration time is different than the total (on-source) time of the observations.  The integration time, set here, is the averaging time for each data point.  The total time spent on-source is set below.  Each pair of antennas will generate a number of data points equal to the total observing time divided by the integration time.
  
We will keep "mapsize" at the default value so that the mosaic will automatically cover the entire image.  In our case, this will require a mosaic of 6 pointings (as we will see later on).  One could also set an exact output image size via <tt>mapsize = ['10arcmin','10arcmin']</tt> for example.
+
We will keep <tt>direction</tt> at the default (blank) value to center the observations on the model coordinates, as given in <tt>indirection</tt> above.
  
The mosaic default pattern "maptype" is 'hexagonal', which we will also leave unchanged.
+
We will keep <tt>mapsize</tt> at the default value so that the mosaic will automatically cover the entire image.  In our case, this will require a mosaic of 6 pointings (as we will see later on).  One could also set an exact output image size via <tt>mapsize = ['10arcmin','10arcmin']</tt> for example.
  
Finally, we will also leave "pointingspacing" to its default value (blank), which automatically sets the pointings to be half a primary beam apart, corresponding to Nyquist sampling.   
+
The default mosaic pattern, <tt>maptype = 'ALMA'</tt>, tells <tt>sim_observe</tt> to use the same hexagonal algorithm as the ALMA OTWe will leave this unchanged.
  
<source lang="python">
+
Finally, we will also leave <tt>pointingspacing</tt> to its default value (blank), which automatically sets the pointings to be half a primary beam apart, corresponding to Nyquist sampling.
integration = '600s'
 
</source>
 
  
 
====Antenna Positions and Total Observation Time====
 
====Antenna Positions and Total Observation Time====
  
Now we will consider the parameters within "predict".  We will keep the default values for every parameter (including "totaltime" = 7200 seconds) except "antennalist", which tells simdata the locations and sizes of each antenna in the array.  We will simulate an Early Science observation, so we will first find the location where CASA has stored the ALMA configuration files.  Then we will tell simdata to use the configuration file designed for Early Science.
+
We will now consider the subparameters available when <tt>observe = True</tt>.  We will keep the default values for every parameter (including <tt>totaltime = 7200s</tt>) except <tt>antennalist</tt>, which tells <tt>sim_observe</tt> the locations and sizes of each antenna in the array.  We will simulate an Early Science observation, so we will first find the location where CASA has stored the ALMA configuration files.  Then we will tell <tt>sim_observe</tt> to use the configuration file designed for Early Science.
  
 
<source lang="python">
 
<source lang="python">
#Set the path where CASA has stored the ALMA configuration files
+
#In CASA
 
repodir = os.getenv("CASAPATH").split(' ')[0]
 
repodir = os.getenv("CASAPATH").split(' ')[0]
 
antennalist =  repodir+"/data/alma/simmos/alma.cycle0.compact.cfg"
 
antennalist =  repodir+"/data/alma/simmos/alma.cycle0.compact.cfg"
 
</source>
 
</source>
  
The first line, run within CASA, uses a linux command to determine the path for CASA.  The second line sets the "antennalist" parameter to the Early Science configuration.  Other .cfg files in the same directory exist for various ALMA Full Science array configurations as well as the configuration files for other radio interferometers.  
+
The first line, run within CASA, uses a Linux command to determine the path for CASA.  The second line sets the <tt>antennalist</tt> parameter to the Early Science configuration.  Other <tt>.cfg</tt> files in the same directory exist for various ALMA Full Science array configurations as well as the configuration files for other radio interferometers.  
  
Most of the other parameters are not relevant for this simulation as we are not using a component list to describe the sky emission, we do not want to simulate observations of a calibrator, and we do not want to simulate single dish observations.  Note that at this stage of simulation development, the time portion of the "refdate" parameter is ignored and all observations are instead centered around transit on the date specified.
+
Most of the other parameters are not relevant for this simulation as we are not using a component list to describe the sky emission, we do not want to simulate observations of a calibrator, and we do not want to simulate single dish observations.  Note that at this stage of simulation development, the time portion of the <tt>refdate</tt> parameter is ignored and all observations are instead centered around transit on the date specified.
  
 
====Thermal Noise====
 
====Thermal Noise====
  
For this simple simulation, we will not include any thermal noise in the observations, so we can leave "thermalnoise" at its default (blank) value.
+
For this simple simulation, we will not include any thermal noise in the observations, so we can leave <tt>thermalnoise</tt> at its default (blank) value.
 +
 
 +
===<tt>sim_observe</tt> Execution and Output===
 +
 
 +
With all the input parameters set, we are ready to execute the task:
  
===Choosing Simdata Output Images===
+
<source lang="python">
[[Image:NewUsersGuide3.2.image.analyze.png|thumb|Screen shot of input parameters for "image" and "analyze"]]
+
#In CASA
 +
sim_observe()
 +
</source>
  
Now that simdata has been told how to simulate the visibilities, it is time to invert them to make an image of sky as observed with the interferometer.
+
All <tt>sim_observe</tt> output will be written to a directory whose name was given by the <tt>project</tt> parameter, in our case, <tt>project = 'sim'</tt>.  Inside this directory, you will find
 +
[[File:Sim.observe.png|thumb|right|The 2x2 summary plot output by <tt>sim_observe</tt> showing source elevation vs. time, antenna position, uv coverage, and the point spread function.]]
 +
# The simulated measurement set (<tt>sim.ms</tt>),
 +
# a CASA image of the point spread function (<tt>sim.quick.psf</tt>),
 +
# a CASA image of the input sky model rescaled according to the <tt>skymodel</tt> sub-parameters (<tt>sim.skymodel</tt>),
 +
# a flattened CASA image of the input sky model rescaled (<tt>sim.skymodel.flat</tt>),
 +
# a flattened PNG image of the input sky model rescaled and overlaid with the mosaic pattern specified by the <tt>setpointings</tt> sub-parameters (<tt>sim.skymodel.png</tt>),
 +
# a 2x2 PNG summary plot (<tt>sim.observe.png</tt>) showing,
 +
## source elevation vs. time,
 +
## antenna position,
 +
## uv coverage,
 +
## and the point spread function,
 +
# and an ASCII text listing of mosaic pointings.
 +
When <tt>sim_observe</tt> is executed, the 2x2 PNG plot will be displayed in the CASA plotter.
  
====Image====
+
==Using <tt>sim_analyze</tt>==
  
We would like to make a deconvolved output image, but we don't want to spend too much time optimizing the cleaning.  So, all we need to do is make sure the "image" parameter is set to True (which it is by default) and leave all of its sub-parameters at their default values.  Other [http://casaguides.nrao.edu/index.php?title=Main_Page data reduction guides] describe the process of cleaning in greater detail.
+
Now that <tt>sim_observe</tt> has created a simulated set of visibility measurements, we are ready to image the visibilities and analyze the result.  The task <tt>sim_analyze</tt> has been created to easily perform the imaging and subsequent generation of useful analysis plots and figures.  We begin by resetting the <tt>sim_analyze</tt> inputs to their default values.
 +
 
 +
<source lang="python">
 +
#In CASA
 +
default sim_analyze
 +
</source>
 +
 
 +
We next setup the imaging and analysis input parameters.
 +
 
 +
===Image===
 +
 
 +
We want to make a deconvolved output image, but we don't want to spend too much time optimizing the cleaning.  So, all we need to do is make sure the "image" parameter is set to True (which it is by default) and leave all of its sub-parameters at their default values.  Other [http://casaguides.nrao.edu/index.php?title=Main_Page data reduction guides] describe the process of imaging in greater detail.
  
 
For simulations intended for a proposal or scientific analysis, one would almost certainly want to choose a more appropriate cleaning threshold and define the region to be cleaned.  Instructions for how to define the region to be cleaned with the "mask" parameter can be found by typing
 
For simulations intended for a proposal or scientific analysis, one would almost certainly want to choose a more appropriate cleaning threshold and define the region to be cleaned.  Instructions for how to define the region to be cleaned with the "mask" parameter can be found by typing
Line 156: Line 179:
 
or by looking at the [http://casaguides.nrao.edu/index.php?title=Clean Clean CASA Guide page].
 
or by looking at the [http://casaguides.nrao.edu/index.php?title=Clean Clean CASA Guide page].
  
====Analyze====
+
===Analyze===
  
To choose which six output images you would like simdata to create (you are limited to 6), set the parameter "analyze" to True and then pick your favorite outputs.  In this example we will look at  
+
To specify how <tt>sim_analyze</tt> displays the imaged data, set the parameter "analyze" to True and then pick your favorite output formats.  If the <tt>graphics</tt> parameter is set to 'screen' or 'both', up to six output formats will be displayed in the CASA plotter.  More than six outputs can be written to disk (<tt>graphics = 'file'</tt> or <tt>'both'</tt>), but only six can be displayed in the plotter.  In this example we will look at,
  
# Locations of the antennas
+
# the uv coverage in the 2 hour observation,
# uv coverage in the 2 hour observation
+
# the synthesized beam (point spread function),
# Synthesized beam (point spread function)
+
# the original sky model (as defined in "modifymodel"),
# Original sky model (as defined in "modifymodel")
+
# the convolved model (sky model convolved with the synthesized beam),
# Convolved model (sky model convolved with the synthesized beam)
+
# the clean image (the sky as observed with the interferometer after deconvolution),
# Clean image (the sky as observed with the interferometer after deconvolution)  
+
# and the difference between the clean image and the convolved model.
  
 
To make these choices, use the following lines in CASA
 
To make these choices, use the following lines in CASA
  
 
<source lang="python">
 
<source lang="python">
 +
#In CASA
 
analyze = True
 
analyze = True
showarray = True
 
 
showconvolved = True
 
showconvolved = True
showdifference = False
 
 
showfidelity = False
 
showfidelity = False
 
</source>
 
</source>
  
====Final Check====
+
===<tt>sim_analyze</tt> Execution and Output===
[[Image:Simdata_inp_example2.png|thumb|Screen shot of "inp simdata".  This screen shot reflects all inputs as they should be set according to this tutorial, before running simdata.]]
 
 
 
Finally, check that everything looks correct.  Look at the simdata inputs and compare with the screen shot at the right.
 
  
> inp simdata
+
[[File:Sim.analysis 2.png|thumb|right| Plot of the six outputs generated by <tt>sim_analyze</tt>.]]
  
If everything looks promising (parameters set with unallowed values will be in red), then run simdata.
+
Execute <tt>sim_analyze</tt> by typing,
  
 
<source lang="python">
 
<source lang="python">
simdata()
+
#In CASA
 +
sim_analyze()
 
</source>
 
</source>
  
==Simdata Output Images==
+
The six outputs we selected will be displayed in the CASA plotter and written to disk in the <tt>sim</tt> directory.   
 
 
Simdata will display output images to your screen, partly based on your selections in "analyze".  It will also produce images that you can display for yourself using the viewer tool that comes with CASA.
 
 
 
===Figures Plotted to the Screen===
 
 
 
When simdata is run with the parameters set as above, the images plotted to the screen are:
 
 
 
# The model image, rescaled as defined in "modifymodel", with the mosaic pointings as defined in "setpointings" [[Image:Sim.skymodel.png|thumb|Input (sky model) image with mosaic pointings overlayed]]
 
# Plots related to "predict", with
 
## Source elevation vs. time
 
## The positions of the antennas
 
## The uv coverage
 
## The synthesized beam (psf)
 
# Images of the 30 Doradus
 
## The original image, as defined in "modifymodel"
 
## The original image convolved with the psf
 
## The "observed" image
 
## The difference between the observed and original images
 
# The images requested in "analyze" [[Image:NewUsersGuide.3.2_sim.analysis.png|thumb|Plots requested in "analyze"]]
 
## The antenna plot
 
## The uv coverage
 
## The synthesized beam
 
## The sky model image
 
## The convolved sky model
 
## The "observed" image
 
 
 
The images requested in "analyze" will be the ones that stay on your screen when simdata is done, while the others will be briefly displayed and then disappear when the next set of images is plotted.  If the images don't stay on your screen long enough to analyze, you can make simdata save the images as .png files with the "graphics" parameter.
 
 
 
  > graphics = 'file'
 
  
===Using Viewer===
+
[[File:30Doradus.sim.image.png|thumb|right| Screen shot of the 30 Doradus image shown in the CASA viewer.]]
[[Image:NewUsersGuide3.2.Viewer.Load.png|thumb|Simdata-generated images that can be loaded with the CASA viewer]]
 
  
Simdata also creates several images that can be displayed with the CASA viewer toolThe viewer can be launched within CASA by typing
+
All CASA images written to disk can be opened later using the CASA viewer.  Just type
 
  > viewer
 
  > viewer
 +
at the CASA prompt to start the viewer tool, and navigate to the appropriate directory, in our case <tt>sim</tt>.  To display the simulated observations, first click on sim.alma.cycle0.compact.image, then click the "raster image" button and then click "done".  The image will be shown in the viewer, and clicking on the picture of the wrench in the upper left corner will allow you to alter the image in many ways, such as changing the color scale, changing the coordinate scale, and axis labels.  The image to the right was created by:
  
Double click on the directory that contains the image files.  In this example, that directory is called "sim", which is the default value of simdata's input parameter "project".
+
# changing <tt>basic settings -> color map</tt> from "Rainbow 2" to "Hot Metal 1",
You will be shown several files that you can view, including those made by CASA and the original FITS image.  Some of the more important images are:
+
# changing <tt>beam ellipse -> beam style</tt> from "outline" to "filled",
* sim.image - The simulated observations
+
# and changing <tt>color wedge -> display color wedge</tt> from "No" to "Yes".
* sim.skymodel - The input map/cube as defined in "modifymodel"
 
* sim.psf - The synthesized beam
 
* sim.residual - The difference between the sky model and the simulated observations
 
 
 
[[Image:NewUsersGuide3.2.Viewer.Image.png|thumb|The simulated image displayed in the CASA viewer]]
 
 
 
To display the simulated observations, first click on sim.image, then click the "raster image" button and then click "done".  The image will be shown in the viewer, and clicking on the picture of the wrench in the upper left corner will allow you to alter the image in many ways, such as changing the color scale, changing the coordinate scale, and axis labels.  The image to the right was created by:
 
 
 
# Changing "basic settings -> color map" from Rainbow 2 to Hot Metal 1
 
# Changing "beam ellipse -> beam style" from outline to filled
 
# Changing "color wedge -> display color wedge" from No to Yes  
 
  
 
You can learn much more about the functionality of the CASA viewer by watching this [http://casa.nrao.edu/CasaViewerDemo/casaViewerDemo.html instructional video].
 
You can learn much more about the functionality of the CASA viewer by watching this [http://casa.nrao.edu/CasaViewerDemo/casaViewerDemo.html instructional video].
Line 247: Line 227:
  
 
[[Category: Simulations]] [[Category:ALMA]]
 
[[Category: Simulations]] [[Category:ALMA]]
 
+
{{Checked 3.3.0}}
{{Checked 3.2.0}}
 

Latest revision as of 10:14, 22 November 2011

Simulating Observations in CASA

This guide is applicable to CASA version 3.3. For simulation instructions for older versions of CASA see Simdata New Users Guide (CASA 3.2).

To create a script of the Python code on this page see Extracting scripts from these tutorials.

Explanation of the guide

When planning an interferometric observation it is useful to simulate the output of the instrument under a variety of conditions. In CASA, interferometric observations can be simulated using task sim_observe and quickly analyzed using task sim_analyze. This guide will demonstrate how to simulate an ALMA observation using these tasks. (Task sim_observe can also be used to simulate observations with other interferometers, but this currently requires advanced techniques not covered here.)

We begin with an image similar to something that might be observed with ALMA. We show how to rescale the image and specify the ALMA antenna configuration. We produce a simulated set of visibility measurements and then produce an image from the visibility data. In the process, we also generate useful figures to help us analyze the simulated output.

We will assume throughout only a general knowledge of interferometry and no specific knowledge of CASA.

Getting Started

The two things you need to get started are

  1. The image we will work with, and
  2. CASA version 3.3.

We will use the Spitzer IRAC 8 micron image of 30 Doradus, which you can download from the Simulation Inputs CASA Guide page.

To install CASA, follow the instructions given on the Obtaining CASA page.

CASA Basics

CASA is the post-processing package for ALMA and EVLA and can handle both interferometric and single dish data. Because sim_observe and sim_analyze are tasks within CASA, we start here with a brief introduction to some CASA basics. To learn much more about CASA, go to the CASA homepage. Walk-throughs of CASA data reduction for a variety of data sets can be found on the CASA Guides website.

Once you have installed CASA, you can launch it by typing "casapy" at the prompt or by double-clicking on the icon, depending on your system and preferences.

Screen shot of inp sim_observe. Note that default values are shown in black, valid and non-default values are shown in blue, and invalid values are shown in red. Expandable parameters have a grey background.

To see a list of all available CASA tasks, at the CASA prompt type

tasklist

To look at the inputs for an available task, use "inp". For instance

inp sim_observe

Any parameter with a grey background is expandable. Black text shows a default value. Red text shows an invalid value. Blue text shows a valid value different from the default.

To get help on a given task, use "help" (to exit from help, hit the "q" key). For instance

help sim_analyze

To reset a task to its default values, use "default". For instance

default sim_observe

To run a task using the current global values of its input parameters, just type its name at the CASA prompt. For instance

sim_observe

It's a good idea to double-check these values (i.e., re-run inp sim_observe) immediately before running a task.

Using sim_observe

The task sim_observe uses a model image along with a number of input parameters that define the observational conditions and alter the input model. The output of sim_observe is a visibility measurement set and various diagnostic plots and images.

Getting Your Input Image Into sim_observe

First, we'll tell sim_observe where to find the model (input) image and how to scale it appropriately for our purposes. Just to be safe, we'll begin by restoring the default values of sim_observe and then set the 30 Doradus image as the skymodel (Note: you might need to include the path to your model image, if you are not currently in the working directory where the image is).

#In CASA
default sim_observe
skymodel = '30dor.fits'

Angular Scale

If you open the FITS image of 30 Doradus in your favorite viewer (e.g. viewer in CASA), you will see that it covers quite a large footprint on the sky, about 10' on a side. We are going to tell sim_observe to rescale the pixels to shrink the image by roughly a factor of 15 (from 2.3" to 0.15" pixels through the incell parameter) so that the model is approximately 40" on a side. This rescaled model will fit within a small mosaic of 6 pointings. Although we do this primarily for convenience in this example, a scientific motivation for this type of rescaling would be to approximate what a super-giant HII region like 30 Doradus would look like if moved from the Large Magellanic Cloud to the distance of M33 or M31. For the sake of demonstration, we will also change the coordinates of the center of the map (using the indirection parameter). Units are case sensitive, so please take care to enter them in verbatim. CASA will throw an error otherwise.

#In CASA
incell = '0.15arcsec'
indirection = 'J2000 10h00m00 -40d00m00'

Observed Wavelength

The model image of 30 Doradus shows 8 micron continuum emission. ALMA does not observe at wavelengths this short, so we will tell sim_observe that this is actually a 230 GHz (1.3 mm) continuum map. We will also tell sim_observe that the observations were taken with a 2-GHz bandwidth. Although for this particular example the channel width is not a critical number, it would be very important if we were modifying a spectral cube instead of a continuum image.

#In CASA
incenter = '230GHz'
inwidth = '2GHz'

Brightness Scale

The 8 micron emission is probably not a great approximation for the millimeter emission from 30 Doradus. For a true science case, one would want to calculate what the expected 230 GHz emission would be from an object like this at the distance of about 750 kiloparsec. For the sake of simplicity, we will rescale the image so that the brightest pixel in the map has a flux density of 0.06 mJy. This number is chosen such that the extended emission is a factor of a few brighter than the expected noise in a 2 hour observation. The ALMA sensitivity calculator can be used to determine the expected noise for an observation.

#In CASA
inbright = '0.06mJy/pixel'

Remember that you can check your task inputs at any time by typing inp at the casa prompt.

Defining the Mock Observations

Now that sim_observe knows how to interpret the input image, the next step is to define the simulated observations.

Pointings and Scan Time

We will first change the parameters within setpointings.

The default value for integration, 10 seconds, might be appropriate to simulate real observations. However, sim_observe will run much faster if the value for "integration" is increased, reducing the number of data points to be generated. In this demonstration we will set it to 600 seconds. When sim_observe is used for scientific purposes it may be best to set integration to a large value at first to make sure that sim_observe runs as expected, and then decrease integration to a more realistic time for the final run. You will get a more accurate simulation with 10 second integrations than with 600 second integrations, especially in Early Science observations with a limited number of baselines.

#In CASA
integration = '600s'

Note that the integration time is different than the total (on-source) time of the observations. The integration time, set here, is the averaging time for each data point. The total time spent on-source is set below. Each pair of antennas will generate a number of data points equal to the total observing time divided by the integration time.

We will keep direction at the default (blank) value to center the observations on the model coordinates, as given in indirection above.

We will keep mapsize at the default value so that the mosaic will automatically cover the entire image. In our case, this will require a mosaic of 6 pointings (as we will see later on). One could also set an exact output image size via mapsize = ['10arcmin','10arcmin'] for example.

The default mosaic pattern, maptype = 'ALMA', tells sim_observe to use the same hexagonal algorithm as the ALMA OT. We will leave this unchanged.

Finally, we will also leave pointingspacing to its default value (blank), which automatically sets the pointings to be half a primary beam apart, corresponding to Nyquist sampling.

Antenna Positions and Total Observation Time

We will now consider the subparameters available when observe = True. We will keep the default values for every parameter (including totaltime = 7200s) except antennalist, which tells sim_observe the locations and sizes of each antenna in the array. We will simulate an Early Science observation, so we will first find the location where CASA has stored the ALMA configuration files. Then we will tell sim_observe to use the configuration file designed for Early Science.

#In CASA
repodir = os.getenv("CASAPATH").split(' ')[0]
antennalist =  repodir+"/data/alma/simmos/alma.cycle0.compact.cfg"

The first line, run within CASA, uses a Linux command to determine the path for CASA. The second line sets the antennalist parameter to the Early Science configuration. Other .cfg files in the same directory exist for various ALMA Full Science array configurations as well as the configuration files for other radio interferometers.

Most of the other parameters are not relevant for this simulation as we are not using a component list to describe the sky emission, we do not want to simulate observations of a calibrator, and we do not want to simulate single dish observations. Note that at this stage of simulation development, the time portion of the refdate parameter is ignored and all observations are instead centered around transit on the date specified.

Thermal Noise

For this simple simulation, we will not include any thermal noise in the observations, so we can leave thermalnoise at its default (blank) value.

sim_observe Execution and Output

With all the input parameters set, we are ready to execute the task:

#In CASA
sim_observe()

All sim_observe output will be written to a directory whose name was given by the project parameter, in our case, project = 'sim'. Inside this directory, you will find

The 2x2 summary plot output by sim_observe showing source elevation vs. time, antenna position, uv coverage, and the point spread function.
  1. The simulated measurement set (sim.ms),
  2. a CASA image of the point spread function (sim.quick.psf),
  3. a CASA image of the input sky model rescaled according to the skymodel sub-parameters (sim.skymodel),
  4. a flattened CASA image of the input sky model rescaled (sim.skymodel.flat),
  5. a flattened PNG image of the input sky model rescaled and overlaid with the mosaic pattern specified by the setpointings sub-parameters (sim.skymodel.png),
  6. a 2x2 PNG summary plot (sim.observe.png) showing,
    1. source elevation vs. time,
    2. antenna position,
    3. uv coverage,
    4. and the point spread function,
  7. and an ASCII text listing of mosaic pointings.

When sim_observe is executed, the 2x2 PNG plot will be displayed in the CASA plotter.

Using sim_analyze

Now that sim_observe has created a simulated set of visibility measurements, we are ready to image the visibilities and analyze the result. The task sim_analyze has been created to easily perform the imaging and subsequent generation of useful analysis plots and figures. We begin by resetting the sim_analyze inputs to their default values.

#In CASA
default sim_analyze

We next setup the imaging and analysis input parameters.

Image

We want to make a deconvolved output image, but we don't want to spend too much time optimizing the cleaning. So, all we need to do is make sure the "image" parameter is set to True (which it is by default) and leave all of its sub-parameters at their default values. Other data reduction guides describe the process of imaging in greater detail.

For simulations intended for a proposal or scientific analysis, one would almost certainly want to choose a more appropriate cleaning threshold and define the region to be cleaned. Instructions for how to define the region to be cleaned with the "mask" parameter can be found by typing

> help clean

or by looking at the Clean CASA Guide page.

Analyze

To specify how sim_analyze displays the imaged data, set the parameter "analyze" to True and then pick your favorite output formats. If the graphics parameter is set to 'screen' or 'both', up to six output formats will be displayed in the CASA plotter. More than six outputs can be written to disk (graphics = 'file' or 'both'), but only six can be displayed in the plotter. In this example we will look at,

  1. the uv coverage in the 2 hour observation,
  2. the synthesized beam (point spread function),
  3. the original sky model (as defined in "modifymodel"),
  4. the convolved model (sky model convolved with the synthesized beam),
  5. the clean image (the sky as observed with the interferometer after deconvolution),
  6. and the difference between the clean image and the convolved model.

To make these choices, use the following lines in CASA

#In CASA
analyze = True
showconvolved = True
showfidelity = False

sim_analyze Execution and Output

Plot of the six outputs generated by sim_analyze.

Execute sim_analyze by typing,

#In CASA
sim_analyze()

The six outputs we selected will be displayed in the CASA plotter and written to disk in the sim directory.

Screen shot of the 30 Doradus image shown in the CASA viewer.

All CASA images written to disk can be opened later using the CASA viewer. Just type

> viewer

at the CASA prompt to start the viewer tool, and navigate to the appropriate directory, in our case sim. To display the simulated observations, first click on sim.alma.cycle0.compact.image, then click the "raster image" button and then click "done". The image will be shown in the viewer, and clicking on the picture of the wrench in the upper left corner will allow you to alter the image in many ways, such as changing the color scale, changing the coordinate scale, and axis labels. The image to the right was created by:

  1. changing basic settings -> color map from "Rainbow 2" to "Hot Metal 1",
  2. changing beam ellipse -> beam style from "outline" to "filled",
  3. and changing color wedge -> display color wedge from "No" to "Yes".

You can learn much more about the functionality of the CASA viewer by watching this instructional video.

Simulating Observations in CASA

Last checked on CASA Version 3.3.0.