imcollapse¶

imcollapse(imagename, function='', axes='[0]', outfile='', box='', region='', chans='', stokes='', mask='', overwrite=False, stretch=False)[source]¶

Collapse image along one axis, aggregating pixel values along that axis.

[Description] [Examples] [Development] [Details]

Parameters

imagename (string) - Name of the input image
function (string=’’) - Aggregate function to apply. This can be set one of flux, madm, max, mean, median, min, npts, rms, stddev, sum, variance, xmadm. Must be specified.
axes (variant=’[0]’) - Zero-based axis number(s) or minimal match strings to collapse.
outfile (string=’’) - Name of output CASA image. Must be specified.
outfile != ''
- overwrite (bool=False) - Overwrite output image if it exists?
box (string=’’) - Rectangular region to select in direction plane. Default is to use the entire direction plane.
region (string=’’) - Region selection. Default is to use the full image.
chans (string=’’) - Channels to use. Default is to use all channels.
stokes (string=’’) - Stokes planes to use. Default is to use all Stokes planes.
mask (string=’’) - Mask to use. Default is none.
mask != ''
- stretch (bool=False) - Stretch the mask if necessary and possible?
stretch (bool=False) - Stretch the mask if necessary and possible?

Description

imcollapse task: Collapse image along one axis, aggregating pixel values along that axis.

The imcollapse task collapses an image along a specified axis or set of axes of N pixels into a single pixel on each specified axis. Images with float precision and complex-float precision pixels are supported. It computes the specified aggregate function for pixel values along the specified axes and places those values in the single remaining plane of those axes in the output image.

The reference pixels of the collapsed axes are set to 0 and their reference values are set to the mean of the the first and last values of those axes in the specified region of the input image.

Convolution to a common beam is not performed automatically as part of the preprocessing before the collapse operation occurs. Therefore, if the input image has per-plane beams, then the user should consider first smoothing the data to have the same resolution (e.g., using the tool method ia.convolve2d() or the task imsmooth), and use the resulting image as the input for collapsing.

Parameter descriptions

imagename

Name of image on which to perform the operation.

function

Aggregate function to apply to pixel values. Choices are: ‘flux’ (see below for constraints), ‘madm’ (median absolute deviation from the median), ‘max’, ‘mean’, ‘median’, ‘min’, ‘npts’, ‘rms’, ‘stddev’, ‘sum’, ‘variance’ and ‘xmadm’ (median absolute deviation from the median multipied by x, where x is the reciprocal of \(\Phi^{-1}\) (3/4), where \(\Phi^{-1}\) is the reciprocal of the quantile function. Numerically, x = 1.482602218505602. See e.g. here). Minimal unique matching is supported for the function parameter (e.g. function = ‘r’ will compute the rms of the pixel values, ‘med’ will compute the median, etc.).

If one specifies function=’flux’, the following requirements must be met:

The image must have a direction coordinate,
The image must have at least one beam if the brightness unit is Jy/beam or derived from that. An image with a brightness unit of K (or derivative of that) does not require a beam for this calculation,
The specified axes must be exactly the direction coordinate axes,
Only one of the non-directional axes may be non-degenerate,
The image brightness unit must be conformant with x*y Jy/beam or x*y K, where x is an optional unit (such as km/s for moments images) and y is an optional SI prefix.

axes

Image axes along which to perform the aggregation. Axes can be specified as a single integer or array of integers indicating the zero-based axes along which to collapse the image. Axes may also be specified as a single string or an array of strings which minimally and uniquely match (ignoring case) world axes names in the image (e.g. “dec” or [“ri, “d”] for collapsing along the declination axis or along the right ascension and declination axes, respectively).

outfile

Name of image to write the result of the operation.

General selection: box, chans, stokes, region

Region of interest in which the computation should be performed. See Image Selection Parameters for details.

mask

On-the-fly mask to use. See section Image Masks for details.

overwrite

Automatically overwrite an existing image named outfile? If True and a file by that name already exists, the application will exit with an error. without performing the requested operation.

stretch

Stretch the specified on-the-fly mask along degenerate axes if possible and necessary to conform to the shape of the input image? An error will result if the shape of the specified on-the-fly mask is not, or in the case of stretch =True, cannot be made to conform to the shape of the input image. This parameter is ignored if mask is not specified.

Examples

Example: Collapse a Subimage Along the Spectral Axis

For this example, myimage.im is a 512x512x128x4 (ra,dec,freq,stokes) image.

imagename = "myimage.im"

We want to only collapse the central 256x256 pixel region, so we define a box for the subregion. Similarly, we avoid the 8 edge channels at each end of the band. These are often noisy from the imaging process.

box="127,127,383,383"
chans="8~119"

We specify to collapse along the spectral axis (zero based index), and to use the “mean” algorithm.

function="mean"
axis=2

And finally we specify the output image name and call the imcollapse function.

outfile="collapse_spec_mean.im"
imcollapse(imagename=imagename, outfile=outfile, function=function, axes=axis, box=box, chans=chans)

The resulting image (collapse_spec_mean.im) is 256x256x1x4 in size.

Development: No additional development details

Parameter Details: Detailed descriptions of each function parameter

imagename (string) - Name of the input image

Default: none

Example: imagename=’ngc5921.im’

function (string='') - Function used to compute aggregation of pixel values

along the collapsed axis.

Default: none
Options: flux, madm, max, mean, median, min,
npts, rms, stddev, sum, variance, xmadm
Minimum match is supported for the function
parameter (eg, function=”r” will compute the rms
of the pixel values).
If one specifies function=’flux’, the following
constraints must be true:
1. The image must have a direction coordinate,
2. The image must have at least one beam,
3. The specified axes must be exactly the
direction coordinate axes,
4. Only one of the non-directional axes may be
non-degenerate,
5. The iamge brightness unit must be conformant
with x*yJy/beam, where x is an optional unit
(such as km/s for moments images) and y is an
optional SI prefix.

axes (variant='[0]') - Zero-based axis number(s) or minimal match strings to

collapse.

Default: [0]
Axes can be specified as a single integer or
array of integers indicating the zero-based axes
along which to collapse the image. Axes may also
be specified as a single or array of strings
which minimally and uniquely match (ignoring
case) world axes names in the image (eg “dec” or
[“ri, “d”] for collapsing along the declination
axis or along the right ascension and declination
axes, respectively).

outfile (string='') - Name of output CASA image. Must be specified.

Default: none

Example: outfile=’collapsed.im’

box (string='') - Rectangular region to select in direction plane.

Default: ‘’ (use the entire direction plane)

Example: box=”100,100,200,200”

region (string='') - Region selection.

Default: ‘’ (use the full image)

chans (string='') - Channels to use.

Default: ‘’ (use all channels)

stokes (string='') - Stokes planes to use.

Default: ‘’ (use all stokes planes)

mask (string='') - Mask to use.

Default: none

overwrite (bool=False) - Overwrite output image if it exists?

Default: False

Options: False|True

stretch (bool=False) - Stretch the mask if necessary and possible?

Default: False
Options: False|True
Stretch the input mask if necessary and
possible. Only used if a mask is specified.