Description

immath task: Perform math operations on images

This task evaluates mathematical expressions involving existing image files. The results of the calculations are stored in the  designated output file. The available options are 1) specify a mathematical expression directly, 2) use a pre-defined expression for calculation of spectral index image, polarization intensity, or position angle images. Image file names are specified in imagename, and by default the variables IM0, IM1, ... are used to represent these files in the expression. For option1 (mode = 'evalexpr') explicit notations of file names in the expression are also supported, in which cases the file names must be enclosed in double quotes (") and imagename is ignored. The image files names may be CASA images or FITS images.

NOTE: Index values start at 0; use the imhead task to see the range of index values for each axes.

If the mask has fewer dimensions than the image and if the shape of the dimensions the mask and image have in common are the same, the mask will automatically have the missing dimensions added so it conforms to the image.

For a full description of the allowed syntax and examples, see the LEL pages in the Image Analysis chapter.

NOTE: where indexing and axis numbering are used in the above functions they are 1-based, ie. numbering starts at 1.

If stretch is true and if the number of mask dimensions is less than or equal to the number of image dimensions and some axes in the mask are degenerate while the corresponding axes in the image are not, the mask will be stetched in the degenerate axis dimensions. For example, if the input image has shape [100, 200, 10] and the input mask has shape [100, 200, 1] and stretch is true, the mask will be stretched along the third dimension to shape [100, 200, 10]. However if the mask is shape [100, 200, 2], stretching is not possible and an error will result.

 

NOTES ON MODE='POLA'

The mode='pola' option creates an image of the polarization angle;

$\theta = {1\over{2}}\,tan^{-1}(U/Q)$

If polithresh is set to a value, e.g. ’30uJy/beam’, a mask (’mask0’) is written to the output image and is False for all corresponding linear polarization values below this threshold. This parameter overrides the input parameter mask. Default (’’) means use the value given in mask, or no masking if that value is empty as well.

 

NOTES ON MODE='POLI'

The mode='poli' option creates an image of the total polarized intensity;

$\sqrt{( Q^2+ U^2+ V^2)}$.

If the input image(s) contains only Q and U, or only V, then just those components contribute to the total polarized intensity.

The polarized intensity may optionally be debiased (if sigma > 0). This requires an estimate of the thermal noise level ($\sigma$). The resulting image will be computed using

$\sqrt{(Q^2 + U^2 + V^2 - \sigma^2)}$

In the output image, pixels for which the expression inside the square root is negative are masked, and their values are set to zero. Note that the imagepol tool method po.totpolint also performs this computation (in fact it's what immath calls under the hood in this case), with the added feature that an estimate of sigma can be computed on the fly (see the relevant tool method help for details).

 

CAUTIONS REGARDING OUTPUT IMAGE METADATA

EXCEPT IN THE EXAMPLES GIVEN HERE, THIS APPLICATION MAKES NO ATTEMPT TO DETERMINE WHAT THE CORRECT BRIGHTNESS UNIT OF THE OUTPUT IMAGE SHOULD BE. THIS RESPONSIBILITY LIES SOLELY WITH THE USER. The brightness unit of the output image can be modified using tool method ia.setbrightnessunit or task imhead with mode='put' and hdkey='bunit'.

Note that when multiple image are used in the expression, there is no strict rule which of those images will be used to create the metadata of the output image, unless imagemd is specified. If imagemd is specified, the following rules of metadata copying will be followed:

  1. The pixel data type of the image specified by imagemd and the output image must be the same.
  2. The metadata copied include
    • the coordinate system - thus, the dimensionality of the output image must correspond to the coordinate system to be copied
    • the image_info record - which contains information like the beam(s)
    • the misc_info record - if one exists in the image specified by imagemd
    • the units.
  3. If the output image is a spectral index image, the brightness units are set to the empty string.
  4. If the ouptut image is a polarization angle image, the brightness unit is set to "deg" and the stokes coordinate is set to have a single plane of type of Pangle.

 

TEMPORARY IMAGES

It is often necessary for this task to create intermediate, temporary disk images. The names of these images start with '_immath' and are created in the directory in which the task is run. The task makes reasonable attempts to remove these images before it exits, but there are conceivably instances where the temporary images may not be automatically deleted. If there is no immath instance in progress, it is generally safe to delete these files manually.

 

Task-specific Parameter Summary

mode

Mode of operation. Supported values are 'evalexpr' (evaluate an LEL expression), 'spix' (spectral index computation, although see also task spxfit for a more robust algorithm), 'pola' (polarization angle), and 'poli' (total polarization intensity).

expr

Used when mode='evalexpr'. LEL expression to compute.

varnames

List of normally short strings corresponding to the images given in imagename that can alternatively be used for the image names given in expr when mode='evalexpr'.

sigma

Used if mode = 'poli'. Standard deviation of noise for debiasing.

polithresh

Used if mode = 'pola'. Threshold in linear polarization intensity image below which to mask pixels.

imagemd

Name of image from which metadata should be copied to the output image. The input can be either an image listed in the imagename parameter or any other image on disk. Not specifying this parameter may copy header metadata from any of the input images, which one is not guaranteed.