This task evaluates mathematical expressions involving existing  
    image files. The results of the calculations are stored in the  
    designated output file.  Options are available to specify mathematical  
    expression directly or pre-defined expression for calculation of  
    spectral index image, and polarization intensity and position angle  
    images are available. The image file names imbedded in the expression or  
    specified in the imagename parameter for the pre-defined calculations may  
    be CASA images or FITS images.  
 
 
    NOTE: Index values for axes start at 0 for the box and chans  
          parameters, but at 1 when used with the indexin function  
          in expression. Use the imhead task to see the range of  
          values for each axes.  
 
 
    Keyword arguments:  
    outfile -- The file where the results of the image calculations  
are stored.  Overwriting an existing outfile is not permitted.  
    Default: none;  Example: outfile=’results.im’  
    mode -- mode for mathematical operation  
            Default: evalexpr  
            Options: ’evalexpr’ : evalulate a mathematical expression defined in ’expr’  
                     ’spix’ : spectalindex image  
                     ’pola’ : polarization position angle image  
                     ’poli’ : polarization intesity image  
      >>> mode expandable parameters  
            expr -- (for mode=’evalexpr’) A mathematical expression, with image file names.  
      Image file names MUST be enclosed in double quotes (")  
      Default: none  
      Examples:  
                 Make an image that is image1.im - image2.im  
                   expr=’ ("image1.im" - "image2.im" )’  
                 Clip an image below a value (0.5 in this case)  
                   expr = ’ iif("image1.im">=0.5, "image1.im", 0.0) ’  
                         Note: iif (a, b, c)   a is the boolian expression  
                                               b is the value if true  
                                               c is the value if false  
                 Take the rms value of two images  
                   expr = ’ sqrt("image1.im" * "image1.im" + "image2.im" * "image2.im") ’  
                         Note: No exponentiaion available?  
                 Build an image pixel by pixel from the minimum of (image2.im, 2*image1.im)  
                   expr=’min("image2.im",2*max("image1.im"))’  
            imagename -- (for mode=’spix’,’pola’,’poli’) input image names  
              Default: none;  
              Examples: mode=’spix’; imagename=[’image1.im’,’image2.im’] will calculate  
                       an image of log(S1/S2)/log(f1/f2), where S1 and S2 are fluxes and  
                       f1 and f2 are frequencies  
                       mode=’pola’; imagename=[’imageQ.im’,’imageU.im’] will calculate  
                       an image of polarization angle distribution, where imageQ.im and  
                       imageU.im are Stokes Q and U images, respectively. Calculate 0.5*arctan(U/Q).  
                       mode=’poli’; imagename=[’imageQ.im’,’imageU.im’,’imageV.im’] will calculate  
                       total polarization intensity image, where imageQ.im, imageU.im, imageV.im  
                       are Stokes Q, U, and V images, respectively.  
            sigma - (for mode=’poli’) standard deviation of noise of Stokes images with unit such as  
                    Jy/beam to correct for bias  
              Default: ’0.0Jy/beam’ (= no debiasing)  
    mask -- Name of mask applied to each image in the calculation  
            Default ’’ means no mask;  Example: mask=’orion.mask’.  
    region -- File path to an ImageRegion file.  
            An ImageRegion file can be created with the CASA  
            viewer’s region manager.  Typically ImageRegion files  
            will have the suffix ’.rgn’.  If a region file is given  
            then the box, chans, and stokes selections whill be  
            ignored.  
            Default: none  
            Example: region=’myimage.im.rgn’  
    box --  A box region on the directional plane  
    Only pixel values acceptable at this time.  
    Default: none (whole 2-D plane);  Example: box=’10,10,50,50’  
    chans -- channel numbers, velocity, and/or frequency  
    Only channel numbers acceptable at this time.  
    Default: none (all);  Example: chans=’3~20’  
    stokes -- Stokes parameters to image, may or may not be separated  
            by commas but best if you use commas.  
            Default: none (all); Example: stokes=’IQUV’;  
            Options: ’I’,’Q’,’U’,’V’,’RR’,’RL’,’LR’,’LL’,’XX’,’YX’,’XY’,’YY’, ...  
 
    Available functions in the expr and mask paramters:  
    pi(), e(), sin(), sinh(), asinh(), cos(), cosh(), tan(), tanh(),  
    atan(), exp(), log(), log10(), pow(), sqrt(), complex(), conj()  
    real(), imag(), abs(), arg(), phase(), aplitude(), min(), max()  
    round(), isgn(), floor(), ceil(), rebin(), spectralindex(), pa(),  
    iif(), indexin(), replace(), ...  
 
    For a full description of the allowed syntax see the  
    Lattice Expression Language (LEL) documentation on the at:  
    http://aips2.nrao.edu/docs/notes/223/223.html  
 
    NOTE: where indexing and axis numbering are used in the above  
    functions they are 1-based, ie. numbering starts at 1.  
 
 
    Examples:  
    # Double all values in an image.  
    immath( expr=’"myimage.im"*2’, outfile=’double.im’ )  
 
    # Taking the sin of an image and adding it to another  
    # Note that the images need to be the same size  
    immath(expr=’sin("image2.im")+"image1.im"’,outfile=’newImage.im’)  
 
    # Adding only the plane associated with the ’V’ stokes value and  
    # the 1st channel together in two images  
    immath(expr=’"image1"+"image2"’,chans=’1’,stokes=’V’)  
 
 
    # Selecting a single plane (5th channel), of the 3-D cube and  
    # adding it to the original image.  In this example the 2-D plane  
    # gets expanded out and the values are applied to each plane in the  
    # 3-D cube.  
    default(’immath’)  
    outfile=’chanFive.im’  
    expr=’"ngc7538.image"  
    chans=’5’  
    go  
    default(’immath’)  
    outfile=’ngc7538_chanFive.im’  
    expr=’"ngc7538.image"+"chanFive.im"’  
    go  
 
    # Selecting and saving the inner 3/4 of an image for channels 40,42,44  
    # as well as channels less than 10  
    default(’immath’)  
    expr=’"my_image.im"’  
    box=’25,25,123,123’  
    chans=’<10;40,42,44’  
    outfile=’my_image_inner.im’ )  
    go  
 
    # Dividing an image by another, making sure we aren’t dividing by zero  
    default(’immath’)  
    expr=’"orion.image"/iif("my.image"==0,1.0,"my.image")’  
    outfile=’my_orion.image’  
    go  
 
    # Applying a mask to all of the images in the expression  
    default(’immath’)  
    expr=’("ngc7538.image"*10)+"ngc7538_clean.image"’  
    mask=’"ngc7538.mask"’  
    outfile=’really_noisy_ngc7538.image’  
    go  
 
 
    # Applying a pixel mask contained in the image information  
    default(’immath’)  
    expr=’"ngc5921.image"*10"’  
    mask=’mask("ngc5921.mask")’  
    outfile=’ngc5921.masked.image’  
    go  
 
    # Creating a Polarization Itensity image from an [Q, U, V] image.  
    default(’immath’)  
    outfile=’Q.im’; expr=’"3C138_pcal"’; stokes=’Q’; go();  
    outfile=’U.im’; expr=’"3C138_pcal"’; stokes=’U’; go();  
    outfile=’V.im’; expr=’"3C138_pcal"’; stokes=’V’; go();  
    #  
    outfile=’pol_intensity’  
    stokes=’’  
    expr=’sqrt("Q.im"*"Q.im" + "U.im"*"U.im" + "V.im"*"V.im" )’  
    go  
    # or using pre-defined expression  
    default(’immath’)  
    outfile=’pol_intensity’  
    mode=’poli’  
    imagename=[’Q.im’,’U.im’,’V.im’]  
    go  
 
    # Creating a polarization position angle image  
    default(’immath’)  
    outfile=’pol_angle.im’  
    mode=’pola’  
    imagename=[’Q.im’,’U.im’] # order of the two Stokes images does not matter  
    go  
 
    # Creating a spectral index image from the images at two different observing frequencies  
    default(’immath’)  
    outfile=’mySource_sp.im’  
    mode=’spix’  
    imagename=[’mySource_5GHz.im’,’mySource_8GHz.im’]  
    go