casa-proc 0.1.dev2
Run CASA scripts within Python
License: MIT
Requires Python: >=3.6, <4
Keywords: CASA

casa-proc
==============================================================

**casa-proc** provides you a quick access of the functions from the `CASA package <https://casa.nrao.edu>`_ under Python, i.e., 
calling CASA tasks or running a user script originally intended for CASA sessions.
The program is essentially a basic Python wrapper around the CASA package, by sending data processing 
jobs to CASA installed on your OS using its script execution option ``casa -c``.
However, some user-friendly features are built in the wrapper:

- behave like a traditional Python module, easy to use interactively or embed into a Python program
- no complicated dependency requirement / no modification needed on your CASA package
- support Python logging

Project links:

* Repo: https://github.com/r-xue/casa-proc
* PyPI: https://pypi.python.org/pypi/casa-proc


Installation
~~~~~~~~~~~~
The command line script can be installed via::

    pip install --user .                                                # from a local copy 
    pip install --user --upgrade casa-proc                              # from PyPI
    pip install https://github.com/r-xue/casa-proc/archive/master.zip   # from GitHub

Usage
~~~~~

To run a single CASA task::

    import casa_proc
    casa_proc.casa_task('listobs','data/hxmm01.band6.ms',field='*')

To run a user CASA script built into the package or written by yourself::

    casa_proc.casa_script('casascript_demo.py',var1='var1_value',var2='var2_value',var3=1,var4=2)

note: `casascript_demo.py <https://github.com/r-xue/casa-proc/blob/master/demo/casascript_demo.py>`_ here is a CASA user example script.

More advanced features (e.g. the logging management) are show in the Jupyter Notebook: `test_casaproc.ipynb <https://github.com/r-xue/casa-proc/blob/master/demo/test_casaproc.ipynb>`_

Compatibility and Dependency
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _below:

The program is only tested against Python>=3.6 on MacOS, though I expect no issue under any Unix-like system if the below requirements are met:

* Python (>=3.5)
* CASA (>=5.x)

The program will automatically create two customized CASA session startup files (``init.py`` and ``prelude.py``) under a scratch folder beneath the CASA preference directory named ``~/.casa/casa_proc/``.

Status
~~~~~~

The code was originally written as a submodule of another Python-based software program I am working on.
Although the shell/wrapper approach is not an efficient solution to run complicated CASA workflows due to the heavy execution overhead,
the program might still be a useful lightweight tool for some user cases.
If you realize that you have been switching back/forth between Python/iPython and CASA too often, this module may help.

Another practice of mixing Python-CASA functions/modules is of course installing various Python modules into 
CASA via `casa-python <https://github.com/radio-astro-tools/casa-python>`_.
Then you can run your external Python function/modules under the CASA interpreter and call it a day.
However, the Python environment / interpreter / modules (e.g. matplotlib) embedded in the current CASA package (specified v5.6 here) are out-of-date (however, see my CASA6 demo below)
Then the maintenance of your Python codes may become rather complicated as this requires all your externally installed Python modules to be compatible with the Python bundled with CASA. 

**This package may become unnecessary in near future**. As part of the ongoing development of 
`CASA 6 <https://science.nrao.edu/enews/casa_008/index.shtml#casa6>`_, and `the transition from Python 2 to 3 <https://science.nrao.edu/enews/casa_006/index.shtml#python>`_, 
CASA will allow to integrate its tasks/tools into your existing Python workflows. The CASA tools and tasks will become standard Python modules as I demonstrate in this Jupyter Notebook:
`test_casa6.ipynb <https://github.com/r-xue/casa-proc/blob/master/demo/test_casa6.ipynb>`_

Note:

* if your sole purpose is to access/manipulate a Measurement Set from Python, `python-casacore <https://github.com/casacore/python-casacore>`_ will be the best solution.
* Some other solutions are available for resolving the same issue (accessing CASA functions from Python). I list some of them here as references:

    * `drive-casa <https://github.com/timstaley/drive-casa/tree/casa-release-5>`_
    * `pkgw-forge <https://newton.cx/~peter/howto/access-casa-in-python-without-casapy>`_