CASA Contributed Script: Mosaicking Utilities

From CASA Guides
Jump to navigationJump to search

Mosaicking Utilities

User beware: these are tested but not thoroughly vetted scripts provided without any guarantee.

These are two potentially useful scripts ("buildmosaic" and "buildfluxmap") to aid in mosaic planning. A full-fledged GUI mosaic tool is under development by EVLA staff and RSRO participants but in the meantime these may be useful. They have been used but not heavily tested - please email aleroy at nrao dot edu to suggest improvements or report bugs.

In fact an email to report use would be appreciated, if people actually use these I can simplify the dependencies (put everything in one file), wrap them up in the XML for a task, and strengthen the error-checking.

The scripts are documented - please poke around to see more about the methodology or input parameters.

buildmosaic

ds9 region output of "buildmosaic" overlaid on M31 IR map.
CASA viewer image of the mask "mask_m31.im" used to constrain the above mosaic.

"buildmosaic" allows users to specify a hexagonally packed mosaic and then outputs this mosaic as a text file in one of three formats: EVLA proposal submission tool, simdata pointing file, or ds9 region file. "buildmosaic" is a python routine. To use it, make sure that "buildmosaic.py", "axisutils.py", "constutils.py", and "geoutils.py" all sit in your casapy path (the easiest way to do this is to just drop them into your working directory). Then type

# In CASA
from buildmosaic import buildmosaic

then you can call "buildmosaic". Our test example was to build a large 2 GHz mosaic of M31 and the syntax we used to build this was something like this:

# In CASA
m31_dir = "00h42m44.3s +41d16m09s"
buildmosaic(direction=m31_dir,
               format="evlapst",
               outfile="m31.pst",
               overwrite=True,
               freq=2.0e9, 
               diam=25.0, 
               posang=12.0,
               beamspacing=0.5,
               calcspacing=True,
               maxrad=10.0,
               mask="mask_m31.im",
               sourceroot="M31FIELD_",
               groupname="M31MOSAIC")

This long list of parameters tells "buildmosaic" how to build a hexagonally sampled mosaic - the center, spacing, orientation, and maximum extent - potentially subject to some spatial mask (an image of 1s and 0s, "buildmosaic" keeps only points coincident with a 1) and how to output the data to a text file.

The options to specify the mosaic itself are:

  • "direction" specifies the center of the mosaic as a string.
  • "mask" supplies an optional CASA image containing only 1s and 0s. Only pointings inside the mask are kept (this is an important feature!).
  • "calcspacing" asks the program to calculate the spacing between mosaic points from the frequency and diameter of the telescope.
    • "freq" gives the observing frequency in Hz (used to calculate the primary beam).
    • "diam" gives the diameter of the telescope.
    • "beamspacing" dictates the spacing of pointing centers in units of the FWHM of the primary beam.
  • "spacing_deg" specifies the spacing in degrees (if you don't use "calcspacing").
  • "posang" tilts the hexagonal pattern by this position angle.
  • "maxrad" gives the maximum distance from the center (in degrees) for a pointing to be considered.

The ouput file is specified by

  • "outfile" specifies the text file output.
    • "overwrite" the file if present?
    • "format" specifies the output format ("evlapst", "simdata", or "ds9") of the output file.
    • "sourceroot", "groupname", etc. just feed to the output (specifically when using the PST format). Experiment to see these in use and have a look inside "buildmosaic.py" to see the other options that can be passed to a text file (a ds9 tag, velocity frame, etc.).

buildfluxmap

CASA viewer image of predicted signal-to-noise map of above mosaic.

The second routine provided here gives a rough estimate of the sensitivity of a proposed mosaic. "buildfluxmap" accepts a template astrometry and a proposed mosaic and makes an image proportional to the expected signal-to-noise ratio. It does so by summing the square of the primary beam point by point and taking the square root of the resulting sum (see, e.g., Condon et al. 1998). "buildfluxmap" wants an input of the mosaic in ds9 format - this could be expanded if folks actually use it.

The syntax is to provide it the proposed mosaic "ptgfile", a template image "template" that will be used as the astrometry for the signal to noise file, then to specify the observing frequency "freq" in Hz and telescope diameter "diam" in meters.

# In CASA
from buildfluxmap import buildfluxmap
buildfluxmap(ptgfile="m31_ds9.reg",
                template="mask_m31.im",
                outfile="snr_m31.im",
                freq=1.5e9,
                diam=25.0,
                overwrite=True)