Package: casatools
CASAtoolsIf you are looking for the place to check outCASAwithGit, this is not the right place. The repository to check outCASAcan be foundhere. At some point in the future, this may form the underlying kernel for a future version ofCASA, but at this point, this package is still in gestation.CASAtools is a self-contained python module that provides the tools from theCASAproject. This module only contains the non-GUI tools which are theSWIGbound C++ functionality from CASA.CASAtools can be built and used with eitherPython3.4or3.6. However,CASAtaskscan only be built with Python 3. So if you plan to buildCASAtasks, please ensure that you have a Python 3 interpreter available.MaturityThis is alpha software in every sense of the word. Currently it builds onRedHat Enterprise Linuxand OSX (RHEL6, RHEL7 and OSX 10.12) using the standardCASAdevelopment environment.Building CASAtoolsInstall Dependencies on Red HatThose already working on CASA 5 can install all of the CASAtools dependencies withYUM:-bash-4.2$ yum install casa-toolset-3After doing this, you may need to add RedHat's Python 3 to your $PATH with:-bash-4.2$ source /opt/rh/rh-python36/enableIn addition,Java 8or greater is required. You can check this by looking for 1.8 in the Java version output:-bash-4.2$ /usr/bin/java -version
java version "1.8.0_121"
Java(TM) SE Runtime Environment (build 1.8.0_121-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)
-bash-4.2$Notable DependenciesGNU Scientific Libraryversion2.2or greaterSWIGversion3.0or greaterOpenMPIversion 1.10required when parallelization is enabledInstall Dependencies on MacosInstall Casa 5 dependencies as described here:https://casa.nrao.edu/casadocs-devel/stable/casa-development-team/development-resources/build-configurationInstall Python 3sudo port install python36
sudo port select --set python python36
sudo port select --set python3 python36
# Pip is not technically required but you will probably want it eventually
sudo port install py36-pip
sudo port select --set pip pip36
sudo port select --set pip3 pip36
sudo port select --set python python36CheckoutCheckout the casa6 source code:-bash-4.2$ git clone -q --recursive https://open-bitbucket.nrao.edu/scm/casa/casa6.gitBuildWhile CASAtools can be built with Python 2,CASAtasksrequires Python 3 so it is probably best to build with Python 3 from the start. Make sure that-bash-4.2$ which pythonreturns a path to the Python 3 executable you want to use becauseCASAtasksbuilds with this executable.With the CASA build environment set up, the CASAtools module can be built like:Linux:-bash-4.2$ cd casa6/casatools
-bash-4.2$ autoconf
-bash-4.2$ ./configure
-bash-4.2$ ./setup.py buildMacoscd casa6/casatools
autoconf && CC=/usr/bin/cc CXX=/usr/bin/c++ ./configure && ./setup.py buildA particular version of Python can be selected at configure time like:-bash-4.2$ PYTHON_VERSION=3.4 ./configurebut as noted above,CASAtaskswill use whatever version of python is in your path so it is best to configure yourPATHto get a particular version of Python.Alternate Developer Build For LinuxOn Linux, one can alternately usemake, which supports incremental and parallel builds that are useful for development. In this case, the steps are-bash-4.2$ cd casatools
-bash-4.2$ autoconf
-bash-4.2$ ./configure
-bash-4.2$ ./setup.py genmake
-bash-4.2$ make [debug]The./setup.py genmakecommand creates a file namedmakefilewith the make commands. In general, this file should only be modified if one knows what they are doing. Once themakefilehas been generated, one can make changes to most source files (eg, .cc and .h files) and simply rerun themakecommand to generate an updated build. However, there are cases when earlier commands will have to be rerun. For example, ifac/templates/setup.py.inis modified, commands starting withautoconfwill have to be rerun to generate a newsetup.pyfile.A non-exhaustive list of when./setup.py genmakefollowed bymakewill need to be rerun includes:modification of cerberus files. These are copied by./setup.py genmake;makedoes not deal with themchanges in tool dependencies when modifying<tool>.xmlfiles. If one does not change tool dependencies when modifying<tool>.xmlfiles, they need only rerunmake. However, if a new tool dependency is introduced or an existing dependency removed (eg via a function return value), one will have to start by rerunning./setup.py genmakeso the new dependency can propagate to the themakefile.Thedebugparameter ofmakeis optional. If provided, the resulting build is configured to use the -g option when compiling C and C++ code. Otherwise, the build is configured to be optimized using the -O2 option when compiling C and C++ files. Themakecommand optionally takes the-joption with the number of parallel threads to use while building which can significantly improve build times on multi-core machines, e.g.:-bash-4.2$ make -j8To execute a parallel build with eight threads.See If It WorksIf the build completes successfully, try loading the CASAtools module:-bash-4.2$ PYTHONPATH=build/lib.linux-x86_64-3.6 python3
Python 3.6.3 (default, Jan  9 2018, 10:19:07)
[GCC 4.8.5 20150623 (Red Hat 4.8.5-11)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from casatools import image
>>> ia = image( )
>>> ia.fromshape("mytest.im",[20,20])
2019-03-25 16:15:08     INFO    ImageFactory::createImage       Created Paged image 'mytest.im' of shape [20, 20] with float valued pixels.
True
>>>
-bash-4.2$CASAtools can be configured using~/.casa/config.py. For example, extra data search paths can be added like:-bash-4.2$ cat ~/.casa/config.py
datapath=[ "~/develop/casa/data/unittests" ]
-bash-4.2$Run Available TestsA number of tests have been brought into CASAtools from CASA. To run the tests, you need to check out the CASA test data repository needed for CASAtools unit tests. The full data repository will use about100GBof space. You can check out the full data repository in the following way. Note that the--depth 1will avoid downloading the past history of the repository and save a few Gbytes of space:-bash-4.2$ git clone --depth 1 https://open-bitbucket.nrao.edu/scm/casa/casatestdata.gitAfter the checkout is complete, you must update your CASAtools RC file to indicate where the unit test data can be found. In my case it looks like:-bash-4.2$ cat ~/.casa/config.py
datapath=[ "~/develop/casa/casatestdata/" ]
-bash-4.2$Thedatapathlist specifies directories where CASAtools should look for data files, and should include the directory we just checked out.A few of the casatools tests use the casatestutils module. That is built independently from casatools.
The path to a casatestutils build can be provided via PYTHONPATH prior to running the full suite of tests.After all of this is set, the full suite of tests can be run with:-bash-4.2$ PYTHONPATH=../casatestutils/build/lib ./setup.py testThere are about 28 tests in total. Running all of them takes about 48 minutes.
The test results can be found in subdirectory of the casatools/build directory (e.g.
casatools/build/testing.linux-x86_64-3.6). A separate directory is use for each tool
test script.To run a single set of test, you can just execute the test file:-bash-4.2$ PYTHONPATH=build/lib.macosx-10.12-x86_64-3.6 python tests/tools/coordsys/test_coordsys.pyIf thecasatoolsmodule is already available in yourPYTHONPATH, you would not need to
explicitly specify it on the command line. This would be the case, for example, if you installed
CASAtools via a binaryPyPIwheel. If you want to run a single test from the set, you can specify
it on the command line like:-bash-4.2$ PYTHONPATH=build/lib.linux-x86_64-3.6 python tests/tools/coordsys/test_coordsys.py coordsys_test.test_constructorHere,test_constructoris one test within thecoordsys_testTestCasespecified intest_coordsys.py.Available ToolsTool NameDescriptionagentflaggerTool for manual and automated flaggingatcafillerFiller for ATNF/ATCA RPFITS dataatmosphereAtmosphere modelcalanalysisGet and fit data from a calibration table (CASA 3.4 and later).calibraterSynthesis calibration (self- and cross-)componentlistA tool for the manipulation of groups of componentscoordsysOperations on CoordinateSystemsfunctionalFunctionals handlingimagemetadataOperations on imagemetadataimageOperations on imagesimagepolPolarimetric analysis of imagesimagertool for synthesis imagingiterbotsinktool for synthesis imaginglogsinktool for logsinkmeasuresmeasures toolmiriadfillerTool for the importmiriad taskmsmetadataOperations to retrieve metadata from a measurment setmsOperations on measurement setsmstransformerTool to apply spw and frame transformations in MSquantaquanta tool handles units and quantitiesregionmanagerCreate and manipulate regions of interestsakuraNew single dish tool interface using sakurasdmManipulate or examine SDM datasetssidebandseparatorTool for sideband separationsimulatorTool for simulationsingledishmsNew single dish tool interface to process an MSspectrallinespectral line toolsynthesisdeconvolvertool for synthesis imagingsynthesisimagertool for synthesis imagingsynthesisimstoretool for synthesis imagingsynthesismaskhandlertool for mask handling in sysnthesis imagingsynthesisnormalizertool for synthesis imagingsynthesisutilstool for synthesis imagingtableAccess tables from casapyvlafillertool for VLA filler tasksvpmanagerTool for specifying voltage patterns and primary beamsTool InitializationThe user initalization and customization file for the CASAtools module is~/.casa/config.py. If this file does not exist, then an attempt is mad to import the RC values from casaconfig (i.e.from casatoolrc import *). If thecasatoolrcmodule does not exist inPYTHONPATH, then the default values for all initialization state is used.Changes from Standard CASAWhile the goal was to simply reconstitute theCASA toolswithin a unencumbered python module, deviations were required as work progressed. These deviations are divided into categories based upon whether the change relates to the way the tools behave or the way the XML files are structured.Changes to BehaviorParameter Order--- with standard CASA, theSWIGbinding is exposed directly to the user. While this is often fine, for CASAtools more control was desired over how parameter checking happens and how coersion happens. Because of this, a wrapper is created over the SWIG binding. This wrapper explicitly specifies the order of the parameters. The input parameters come first, followed by the output parameters. Within the input and output parameters, the order is determined by the XML file. With standard CASA, all parameters are largely unordered with binding controlled by the waypython argument listsare handled.Utils Tool--- the standard CASAuttool(AKAutilsor justut), has been converted from a toolbox/grab bagtoolto asingleton objectcalledctsysin CASAtools, e.g.:In [1]: from casatools import ctsysctsys.resolve( )--- a new member function was added to resolve the path to a data file based uponCASADATApath (as is done for<type mustexist="true">path</type>)rc file--- the rc file, which is evaluated at startup to configure CASAtools, is~/.casa/config.py; if this file is not found, then an attempt is mad to import the RC values from casatoolrc (i.e.from casatoolrc import *)Xml ChangesString Constants--- (developer) default values for strings, shouldnotinclude quotes. The standard CASA XML processing would strip out opening and closing quotes, but CASAtools XML processing does not.Path Type Added--- (developer/automatic) a new parameter type calledpathwas added to CASAtools. Thispathtype evolved from the standard CASA convention of adding themustexistattribute to string typed parameters. TheautomaticXML translation converts string parameters which include themustexistattribute to path parameters. C++ receives thepathparameters as a string, but when themustexistattribut of thepathparameter is set totrue, the CASAtools binding layer will expand the required path using theCASADATA(colon separated) path list to locate the required file or directory. In the cases where themustexistattribute was not used, developers must make any changes to convert astringparameter to apathparameter.Type Element Added--- (developer) CASAtools adds a new<type>XML element which has precedence over thetypeattribute, e.g.<param type="...">. This addition allows types that can be passed to aany/variantparam to be enumerated. This allowspathstrings to be expanded by the CASAtools binding layer when thepathis part of anany/variantparameter. When more than one<type>is specified for a parameter, the parameter is assumed to be anany/variantparameter.Bool--- (automatic) The majority of standard CASA XML files indicate boolean type parameters withbool. However, a small number of them useboolean. With CASAtools, onlyboolis accepted.StringArray--- (automatic) The majority of standard CASA XML files indicate the vector of strings type parameters withstringArray. However, a small number of them usestringarray. With CASAtools, onlystringArrayis accepted.Array Values--- (developer) With CASAtools, the behavior<value>elements for vector initialization has been rationalized:<value/>--- empty vector (zero elements)<value><value/></value>--- vector with one element initalized to the default initialization for the vector element type<value><value>0.0</value></value>--- vector with one element initialized as specified, more internal<value>elements can be used to increase the default size of the vectorIt is not possible to automatically adjust these because with the old XML translation<value/>will sometimes result in a one element vector and other times a zero element vector.Array Value Types--- There are now two Array types<type>Arrayand<type>Vec, e.g.doubleArrayanddoubleVec. Vec implies a one dimensional value, e.g. Python list, a one dimensonal numpy array, whereas Array implies potentially an N dimensional numpy array.XMLTool Specification<tool name="tool-name">
        <shortdescription>one-line description</shortdescription>
        <description>paragraph description</description>

        <needs>tool-name</needs>

        <code>
            <include>path to headerfile</include>
            <private>
                <include>path to headerfile</include>
            </private>
        </code>

        <method name="method-name">
            <shortdescription>one-line description</shortdescription>
            <description>paragraph description</description>
            <input>
                <param name="param-name">
                    <description>short description</description>
                    <type units="unit-name" mustexist="true">type-name</type><value>value-content</value></param>
            </input>
            <output>
                <param name="param-name">
                    <description>short description</description>
                    <type units="unit-name" mustexist="true">type-name</type><value>value-content</value></param>
            </output>

            <returns type="type-name"/>
        </method>
    </tool>Red text indicate unique names. They may be developer specified (e.g. tool-name), they may be predefined enumerations (e.g. unit-name), or they may be both (e.g. type-name).Blue XML elements or attributes indicates optional items (zero or one).Green XML elements can be repeated.Black XML elements or attributes must be supplied (once)testing linksmore information for testing