Analysis Utilities

Last checked on CASA Version 6.5.4

Introduction

Analysis Utilities (or analysisUtils for short) is a small set of Python source code files that provide a number of analysis and plotting utilities. The primary file is analysisUtils.py (108000 lines as of March 2021). The utilities were developed (and continue to be developed) for ALMA commissioning and data reduction and are, in many cases, also useful for EVLA data reduction. This CASA Guide documents some of the most useful functions contained in the analysisUtils Python module from a user's perspective, but most of the functions have fairly complete inline help.

Getting Started

If you are working on a machine at NRAO Charlottesville, then you can skip Step 1, because the latest modules are already available at: /users/thunter/AIV/science/analysis_scripts.

Step 1: Download Analysis Utilities There are two options:

a) NRAO ftp server. (If your browser does not want to open an ftp link, then try right click to save the link and select the application to use to be wget.)

b) zenodo (this provides a citeable DOI: 10.5281/zenodo.7502160, on ADS see 2023zndo...7502160H)

Once downloaded, then extract the tar ball. From a Unix command line this can be done with

# In bash
tar xvf analysis_scripts.tar

Seven files will be extracted -- a README file, and six python scripts. The README file contains the time and date that the tar ball was generated, which can be useful for reporting bugs. The history file available at the ftp site contains a list of major changes in each version.

Step 2: Edit your existing casa initialization file (in CASA5: $HOME/.casa/init.py, or in CASA6: $HOME$/.casa/startup.py) or create a new file if it does not already exist, and add the following

# In startup.py
import sys
sys.path.append("/PATH/TO/analysis_scripts")
import analysisUtils as au

where /PATH/TO/analysis_scripts is the path to the directory analysis_scripts you just extracted from the tar ball. An example can be downloaded and edited here: File:Init.py. When this is done, start casapy and you will have access to all the functions contained in the analysisUtils module.

Support

Once installed, functions can be searched for by name via minimum match string with the au.help function (where comma denotes a logical AND): e.g. au.help('antenna') or au.help('spw,caltable'). As in python, inline help for an individual function is accessed by typing 'help au.planet'. For further help with analysisUtils installation or usage, you may submit a helpdesk ticket to the Data Reduction category at https://help.almascience.org/. Be advised that analysisUtils is a commissioning tool, so the level of support available is not as extensive as for CASA, but we do welcome feedback. If your question is with regard to plotbandpass, then please provide the version number of this program (it is printed to the screen at execution time and on the plots). In all cases, please provide the release date of your analysisUtils, which can be viewed from inside casapy as follows:

# In CASA
au.version()

Link to <a href="https://ui.adsabs.harvard.edu/search/fl=identifier%2C%5Bcitations%5D%2Cabstract%2Cauthor%2Cbook_author%2Corcid_pub%2Cpublisher%2Corcid_user%2Corcid_other%2Cbibcode%2Ccitation_count%2Ccomment%2Cdoi%2Cid%2Ckeyword%2Cpage%2Cproperty%2Cpub%2Cpub_raw%2Cpubdate%2Cpubnote%2Cread_count%2Ctitle%2Cvolume%2Cdatabase%2Clinks_data%2Cesources%2Cdata%2Ccitation_count_norm%2Cemail%2Cdoctype&fq=%7B!type%3Daqp%20v%3D%24fq_database%7D&fq_database=(database%3Aastronomy%20OR%20database%3Aphysics)&q=full%3A%22analysisUtils%22%20not%20title%3A%20%22analysisUtils%22&rows=25&sort=date%20desc%2C%20bibcode%20desc&start=0&p_=0">Papers citing analysisUtils on ADS</a>

Script Generators

The documentation for the two script generators almaqa2csg.py and almaqa2isg.py, as well as how to provide feedback or get support for their usage, can be found at this link:
https://confluence.alma.cl/display/EAPR/ALMA+Data+Analysis+Utilities

In Summary:
The analysis package includes an ALMA QA2 Calibration Script Generator (CSG) and Imaging Script Generator (ISG). Based on the properties of the data set, the generator scripts create calibration and imaging scripts tailored to the needs of the particular case. The result is a nearly complete script draft which may work as is but should be inspected to make sure all steps are correct. To view the parameter descriptions for each, use the "help" function. After the script is generated and reviewed, it may be executed in steps by advancing the mysteps index. Several steps may be listed together such as mysteps=[0,1,2].

# In CASA
import almaqa2csg as csg
help csg.generateReducScript
csg.generateReducScript('<my_EB>', parameters...) # input raw data

mysteps = [0]
execfile('scriptForCalibration.py')

# In CASA
import almaqa2isg as isg
help isg.generateImagingScript
isg.generateImagingScript('<my_MS>', parameters...) # input calibrated MS

mysteps = [0]
execfile('scriptForImaging.py')

Some Examples of Functions

Up-to-date, online help is available for all of these functions (and more) at the CASA prompt by simply using the command: help(au.functionName). To search for functions, you can type au.help('phrase'), where phrase is case-insensitive and minimum-match. Multiple phrases can be combined with a comma, for example au.help('baseline,stats').

angularSeparationOfFields

reads an ms and computes the angular separation of all fields, or a subset

buildConfigurationFile

reads the list of antenna stations in an .ms and creates a .cfg file suitable for simobserve

editIntents

change the intents for a specified field in an ms (based on John Lightfoot's pipeline script)

getBaselineLengths

returns a dictionary of the baseline lengths in your ms, by default sorted by length

getBaselineStats

returns a bunch of statistics on the baseline lengths in your ms

gjincBeam

compute the effective restoring beam obtained from the casa command sdimaging when using the GJINC gridding kernel

lstrange

lists the range of LST, UT, MJD for the whole ms, and for scans with OBSERVE_TARGET intent (including the elevation range)

obslist

prints the antenna station coordinates in local offsets from the Center of Array, and computes longest/shortest baselines

planet

contacts the JPL Horizons telnet service and returns the J2000 position, velocity, angular diameter, range and range rate of a solar system object

planetFlux

calls Bryan Butler's solar_system_setjy module in CASA to compute flux density vs. time or flux density vs. frequency

planetPlots

generates a plots of uv amplitude vs. uv distance for a grid of ALMA configurations and observing frequencies

plotbandpass

a faster version of plotcal for bandpass tables, with useful overlay capabilities. This function has been incorporated into CASA as task plotbandpass.

plotSunDuringTrack

generates a plot of the Sun's az vs. el during an ms or ASDM

plotconfig

plot any standard telescope configuration of observatories known to casa, and return an array of the sorted baseline lengths

plotmosaic

shows relative location of pointings in an .ms

plotPWV

reads the PWV from each antenna's WVR from the ASDM_CALWVR table in an ms, and creates a plot vs. time

plotweather

plot weather conditions vs. time for your ms

plotWVRSolutions

plot the WVR solutions in terms of baseline-based phase corrections

spectralindex

performs a least-squares fit to the multi-spw output from fluxscale

timeOnSource

compute the total time spent integrating on-source for each specified field

A list of additional 1200+ functions, and their brief descriptions, can be found at Todd's wikipage