• WideBandImaging

(N.B. A first version of a requirements document was drafted by Simon Garrington towards the end of 2005: wideband_reqs.pdf)

---

Author: I M Stewart, lately of JBCA, now at the University of Cape Town.

Date: 2009-01-15

Description: this document explains the various files in this repository: ims_albus_modules.tar.gz.

1. Description:

---

The accompanying files in this repository are mostly python modules (1 or 2 are perl scripts). Their overall purpose is to clean (or deconvolve) images made by a radio interferometer operating with a bandwidth which is a significant fraction of the base frequency. The algorithm employed is described in the following publication:

• Sault, R. J. & Wieringa, M. H., Astron. Astrophys. Suppl. 108, 585-594 (1994), "Multi-frequency synthesis techniques in radio interferometric imaging."

2. General information:

---

2.0. Copyright and disclaimer:

---

• All code in this repository is covered by the GNU General Public License version 3, see http://www.opensource.org/licenses/gpl-3.0.html, or the copy of this page which is included in the present repository.

2.1. A list of all files included in the repository:

---

• aips_desc2data_3.py

• aips_image_utils_1.py

• aips_lib_2.py

• array_geom_1.py

• basis_fn_types_3.py

• basis_functions_2.py

• beam_uv_template_1.py

• bin_tree_3.py

• bin_tree_file_1.py

• cc_im_make_1.py

• clean_comps_5.py

• cleaned_im_plot_1.py

• do_fft2d_c2r_1.py

• fits_card_replace_2.pl

• fitsdisplay_1.pl

• fits_to_pkl_1.py

• fits_wcs_4.py

• form_dirty_beams_1.py

• gpl-3.0.html

• gram_schmidt_3.py

• gridding_4.py

• ims_utils_6.py

• myaipslib_10.py

• mylib_9.py

• pgplot_aux_2.py

• pgview_pkl_1.py

• pkl_to_fits_1.py

• ranges_3.py

• README

• rgb_pkls_to_fits_1.py

• SciMathConstants_1.py

• sim_grid_2.py

• sim_make_DI_2.py

• sw_array_defs_5.py

• sw_clean_11.py

• sw_tester_5.py

• uvncon_20.py

2.2. How to set up the python modules:

---

Each module has a name of the format <prefix>_<version number>.py. However when importing one module into another, I nearly always omit the version number. Eg a module which has a file name "bloggs_9.py" appears when imported into another module via "import bloggs".

• This can only work if you set up a symlink as follows:

  • ln -s <relevant path name> bloggs.py

  You must put the symlink in a directory which appears in the environment variable PYTHONPATH

2.3. Additional required python modules or other packages:

---

• The following is a non-exhaustive list of non-standard python modules required:
  • numpy
  • Numeric
  • pyfits
  • ppgplot (requires pgplot of course)
  Python will let you know soon enough if you don't have a necessary module installed! Note too that some of these modules need access to AIPS tasks via the parseltongue interface.

3. What you can do with the available modules:

---

The python modules are grouped as follows. I have suppressed the version number and 'py' suffix. I've also indicated whether the module is meant to be run as a stand-alone task, and whether the module has received (sometimes basic) testing. Finally I indicate those tasks or modules which should be run in the ParselTongue environment.

3.1. Utilities

---

'Pickle' refers to the format python uses to write a generic object to file.

3.2. Miscellaneous libraries:

---

3.3. Libraries relevant to interferometry:

---

3.4 Simulations of AIPS-format wide-band visibility datasets:

---

To those not familiar with object-oriented programming, the following three modules may seem a little arcane:

The reason for writing them in this OO fashion is to preserve, at each stage, as much generality as possible.

The first module, bin_tree, is intended to implement a procedure for constructing a composite object from a list of component objects. This binary-addition procedure is, under certain conditions, more efficient than simply sequentially adding the list elements. The nature of the objects is left completely generic: all that is specified is a few simple properties they must possess.

The second module, bin_tree_file, is an example of how the objects manipulated within bin_tree may be implemented (there are of course an unlimited number of ways one could implement them). The nature of the objects is still kept as generic as possible but they are intended to behave like disk files.

The third module, aips_desc2data, finally gets specific: it describes in exact detail one way of describing and constructing the vague file-type objects of bin_tree_file. Here the objects are AIPS visibility datasets in a certain range of frequency channels.

All this machinery is put together in the task which produces the output:

3.5 Simulations of (non-AIPS) wide-band dirty images:

---

This makes gridded beam visibilities (GBVs) for several (at present hard-wired) array- and observation parameters.

Ffts each GBV to give a sky-plane beam.

This uses a (at present hard-wired) set of clean components, plus beam files read in from the command line, to construct a simulated dirty image (DI).

This reads the (pickled) dirty image and beams which have been created by the previous three modules, then calls and applies the S-W algorithm in module sw_clean. The output is a (pickled) list of clean components. You can use the utilities described in section 3.8 to display resulting images.

3.6 The Sault-Wieringa core modules:

---

Initially it was intended to employ AIPS tasks to perform even simple arithmetical operations on images. It was desired to retain the ability to apply the same S-W algorithm code to either AIPS-format images or (for easier testing purposes) python numpy-format image arrays. The specification of the nature of the 'image' object was thus not tied down within the module sw_clean but was intended to reside in a separate module. The crude initial implementation of this had one auxillary module to define the AIPS images and another to define the numpy ones. The idea to use AIPS was abandoned (because of disk I/O overhead), thus only the array definer remains. It would probably be simpler to dispense with much of the amiguity which remains within sw_clean.

In addition to the usual symlink to sw_array_defs_<vers>.py you should also, in the same directory, set up a symlink as follows:

• ln -s ./sw_array_defs.py sw_defs.py

3.7 Machinery to apply the S-W algorithm to real data:

---

Here is more OO-style separation of powers. The function of the modules in this section is to generate S-W dirty beams for real UV data. Expansion of the spectrum and/or the time series in one of several sets of basis functions is supported. (S-W discuss only Taylor expansion of the spectrum but their method is readily generalised.) The user runs form_dirty_beams, and all the machinery is taken care of within the classes defined in the other modules. There are two lots of complicated business which it is desirable to farm out in this way: (i) the detailed description of the set of visibilities (or, more exactly, the positions of these visibility samples in the UV plane) which is to serve as a template for the various beams; plus the construction of the beams from this template; and (ii) the description and implementation of the basis functions themselves.

I am not satisfied with the logic of the 'chunking' as I have written it. I have no doubt that a programmer with more experienced of OO could do a better job.

3.8 Tasks which process S-W output:

---

Takes the output of sw_clean and creates an image of the clean components.

Takes the output of sw_clean and cc_im_make and plots a residual image and a total image.

4. Perl scripts:

---

Supplementary perl scripts are provided as follows:

fitsdisplay_1.pl

This is a translator of FITS to ASCII.

fits_card_replace_2.pl

This script is called by beam_uv_template to fix the FITS files written by FITAB.

5. TODO:

---

• Obviously, finish testing everything.
• Use a proper version-control scheme to avoid the clunky labelling of module file names with version numbers.
• Rationalise the numerous and partially overlapping utility libraries.
• Change all instances of module Numeric to numpy (Numeric was used from the beginning, despite not being as useful as numpy, because until recently the numpy people charged for their documentation.)
• Modify ppgplot so it can use numpy.
• Implement the loop within sw_clean.sault_wieringa_clean() in C (because this would be much faster).
• Submit bug fixes to aips tasks as follows:

  • FITAB: so that it writes 'correct' FITS (as tested by, for example, the HEASARC ftool named 'fverify'). This would make it unnecessary for beam_uv_template.BeamTemplate.init() to call the FITS-patching perl script fits_card_replace.pl.

  • UVCON: so that the task writes an FQ table.