simalma.py

Go to the documentation of this file.

#
# This file was generated using xslt from its XML file
#
# Copyright 2009, Associated Universities Inc., Washington DC
#
import sys
import os
from  casac import *
import string
from taskinit import casalog
#from taskmanager import tm
import task_simalma
def simalma(project='sim', skymodel='', inbright='', indirection='', incell='', incenter='', inwidth='', complist='', compwidth='"8GHz"', setpointings=True, ptgfile='$project.ptg.txt', integration='10s', direction=[''], mapsize=['', ''], antennalist='alma_cycle1_1.cfg', hourangle='transit', totaltime='7200s', acaratio=0.0, acaconfig='', pwv=0.0, image=True, imsize=[128, 128], imdirection='', cell='', niter=500, threshold='0.1mJy', graphics='both', verbose=False, overwrite=False):

        """(Experimental) simple simulation task for ALMA 
ALMA simulation task:

    ##### WARNING: This task is EXPERIMENTAL #####
    This task simulates ALMA observation including 12-m, ACA 7-m and total
    power arrays, and images and analyzes simulated data.
    New functionality is actively being added, so if you have changed
    versions of CASA, check the inputs carefully.
    More information and examples are availible at 
     http://casaguides.nrao.edu/index.php?title=Simulating_Observations_in_CASA
    Please contact CASA experts with any questions, especially 
    about features noted below as *experimental*    
    -------------------------------
    project -- root filename for all output files.
    -------------------------------
    skymodel -- image model of the sky in FITS or CASA image, 
         with optional parameters that can be overridden
    inbright -- peak brightness in Jy/pixel, or "" for unchanged
       * NOTE: "unchanged" will take the numerical values in your image 
         and assume they are in Jy/pixel, even if it says some other unit 
         in the header. 
    indirection -- central direction, or "" for unchanged
    incell -- spatial pixel size, or "" for unchanged
    incenter -- frequency of center channel e.g. "89GHz", or "" for unchanged
    inwidth -- width of channels, or "" for unchanged - this should be a 
         string representing a quantity with units e.g. "10MHz"
       * NOTE: only works reliably with frequencies, not velocities
       * NOTE: it is not possible to change the number of spectral planes
         of the sky model, only to relabel them with different frequencies
         That kind of regridding can be accomplished with the CASA toolkit.
    -------------------------------
    complist -- component list model of the sky, added to or instead of skymodel
    compwidth -- bandwidth of components; if simulating from components only, 
         this defines the bandwidth of the MS and output images
    -------------------------------
    setpointings -- calculate a map of pointings, or if false, provide ptgfile
       * if graphics are on, display the pointings shown on the model image
    ptgfile -- a text file specifying directions in the same 
         format as the example, and optional integration times, e.g.
         #Epoch     RA          DEC      TIME(optional)
         J2000 23h59m28.10 -019d52m12.35 10.0
       * if the time column is not present in the file, it will use
         "integration" for all pointings.
       * NOTE: at this time the file should contain only science pointings:
         simalma will observe these until totaltime is used up. 
    integration --- Time interval for each integration e.g '10s'
       * NOTE: to simulate a "scan" longer than one integration, use 
         setpointings to generate a pointing file, and then edit the 
         file to increase the time at each point to be larger than 
         the parameter integration time.
    direction -- mosaic center direction e.g 'J2000 19h00m00 -40d00m00'
       * can optionally be a list of pointings
       * otherwise simalma will pack mapsize with grids proper for the
         array (see below).
    mapsize -- angular size of map 
       * set to "" to span the model image
    -------------------------------
    antennalist -- ascii file containing antenna positions.
       * NOTE: In this task, it should be an ALMA configuration.
       * standard arrays are found in your CASA data repository, 
         os.getenv("CASAPATH").split()[0]+"/data/alma/simmos/"        
       * a string of the form "alma;0.5arcsec" will be parsed into a full 12m ALMA
         configuration.  This only works for full ALMA and may fail to find the 
         standard configuration files on some systems - see casaguides.nrao.edu
    hourangle -- hour angle of observation e.g. '-3h'
    totaltime --- total time of observation e.g '7200s' or if a number without
         units, interpreted as the number of times to repeat the map
    acaratio  --- ratio of the total observation time of ACA relative to 
         that of 12m array. Set 0 for no ACA observation. 
         For Cycle-1, set acaratio = 0 or 3.
    acaconfig --- ACA configuration. Available configurations are:
       * "" (default) : automatically defines based on antennalist. 
               If antennalist is Cycle-1 configuration, acaconfig='cycle1'.
               Otherwise, acaconfig='i'
       * 'cycle1' : Cycle-1 ACA-7m configuration. Uses 'aca_cycle1.cfg'.
       * "i" : Normal ACA configuration in full operation. Uses 'aca.i.cfg'.
       * "ns": North-South extended configuration in full operation. 
               Uses 'aca.ns.cfg'.
    -------------------------------
    pwv -- precipitable water vapor if constructing an atmospheric model.
         Set 0 for noise-free simulation. When pwv > 0, thermal noise is
         applied to the simulated data.
       * J. Pardo's ATM library will be used to construct anatmospheric
         profile for the ALMA site:
         altitude 5000m, ground pressure 650mbar, relhum=20%, 
         a water layer of user_pwv at altitude of 2km,
         the sky brightness temperature returned by ATM, and internally
         tabulated receiver temperatures.
       See the documents of simobserve for more details.
    -------------------------------
    image -- invert and deconvolve the simulated measurement set(s)
       * NOTE: interactive clean or more parameters than the subset visible
         here are available by simply running the clean task directly.
       * NOTE: the channelization of the output image cube will be the 
         same as that in the simulated Measurement Set.
       * if graphics turned on, display the clean image and residual image
       * uses Cotton-Schwab clean for single fields and Mosaic gridding
         for multiple fields (with Clark PSF calculation in minor cycles).
    imsize -- image size in spatial pixels (x,y)
       0 or -1 will use the model image size; example: imsize=[500,500]
    imdirection -- phase center for synthesized image.  default is to 
       center on the sky model.
    cell -- cell size e.g '10arcsec'.  "" defaults to the skymodel cell
    niter -- number of clean/deconvolution iterations, 0 for no cleaning
    threshold -- flux level to stop cleaning
    -------------------------------
    graphics -- view plots on the screen, saved to file, both, or neither
    verbose -- print extra information to the logger and terminal
    overwrite -- overwrite existing files in the project subdirectory

    -------------------------------
    What does this task do:
    -------------------------------
    simalma is a task to simulate ALMA observation with simple interface. 
    It simulates ALMA 12m observation and optionally ACA 7m and Total power
    observations when acaratio > 0. 
    When image=True, simulated data are imaged and analyzed. CLEAN is used
    to generate image(s) from simulated data. ALMA 12m and ACA data are
    combined (if both geneareted) by taking ACA image as an initial model
    in CLEAN of ALMA 12m data.
    NOTE this task is very experimental and may not exactly reproduce
    actual ALMA products.

    The following assumptions are made to make the interface simple:
    * This task is intended to be run only once with a set of parameters.
      Therefore, it always sets up input model and pointings, and invokes simulation.
      You can stop before imaging step and reduce data manually with the other tasks,
      e.g, simanalyze, clean, and feather.
    * acaratio controls whether or not ACA observation is simulated. if acaratio > 0,
      ACA observation is simulated with total observation time = acaratio * totaltime
      for both ACA 7m and Total power array.
    * pwv controls whether or not thermal noise is applied to simulated data.
      When pwv > 0, the thermal noise is applied to simulated data. J. Pardo's ATM
      library is used to construct an atmospheric profile of the ALMA site.
    * if a list of directions is not specified, ALMA 12m and ACA 7m arrays will
      pack mapsize with the same hex algorithm as the ALMA OT in Nyquist sampling
    * Total power array maps slightly (+1 PB) larger area compared to 12m array for
      later combined imaging. It samples the region with lattice grids of spacing, 
      0.36 lamba/d.

    -------------------------------
    How to specify a model image:
    -------------------------------
    * simalma requires a CASA or fits image. If you merely have a grid of 
      numbers, you will need to write them out as fits or write a CASA script to
      read them in and use the ia tool to create an image and insert the data.
    
    * simalma does NOT require a coordinate system in the header. If the
      coordinate information is incomplete, missing, or you would like to
      override it, set the appropriate "in" paremeters.  
      In the absence of other information, simalma will assume that the axes of 
      your input correspond to RA, Dec, and (optionally) frequency and 
      (optionally) Stokes parameter.  

    * If you have a proper Coordinate System, simalma will do its best to
      generate visibilities from that, and then create a synthesis image
      according to the specified user parameters.  Regridding the
      spectral dimension may not have complete flexibility yet.

    * You can manipulate an image header with the "imhead" task.


    Please see the documents of simobserve and simanalyze for
    the list of outputs produced.


        """
        if type(direction)==str: direction=[direction]
        if type(mapsize)==str: mapsize=[mapsize]
        if type(imsize)==int: imsize=[imsize]

#
#    The following is work around to avoid a bug with current python translation
#
        mytmp = {}

        mytmp['project'] = project
        mytmp['skymodel'] = skymodel
        mytmp['inbright'] = inbright
        mytmp['indirection'] = indirection
        mytmp['incell'] = incell
        mytmp['incenter'] = incenter
        mytmp['inwidth'] = inwidth
        mytmp['complist'] = complist
        mytmp['compwidth'] = compwidth
        mytmp['setpointings'] = setpointings
        mytmp['ptgfile'] = ptgfile
        mytmp['integration'] = integration
        mytmp['direction'] = direction
        mytmp['mapsize'] = mapsize
        mytmp['antennalist'] = antennalist
        mytmp['hourangle'] = hourangle
        mytmp['totaltime'] = totaltime
        mytmp['acaratio'] = acaratio
        mytmp['acaconfig'] = acaconfig
        mytmp['pwv'] = pwv
        mytmp['image'] = image
        mytmp['imsize'] = imsize
        mytmp['imdirection'] = imdirection
        mytmp['cell'] = cell
        mytmp['niter'] = niter
        mytmp['threshold'] = threshold
        mytmp['graphics'] = graphics
        mytmp['verbose'] = verbose
        mytmp['overwrite'] = overwrite
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'simalma.xml')

        casalog.origin('simalma')
        if trec.has_key('simalma') and casac.utils().verify(mytmp, trec['simalma']) :
            result = task_simalma.simalma(project, skymodel, inbright, indirection, incell, incenter, inwidth, complist, compwidth, setpointings, ptgfile, integration, direction, mapsize, antennalist, hourangle, totaltime, acaratio, acaconfig, pwv, image, imsize, imdirection, cell, niter, threshold, graphics, verbose, overwrite)

        else :
          result = False
        return result