# Source code for casatasks.analysis.imcollapse

```
#
# stub function definition file for docstring parsing
#
[docs]def imcollapse(imagename, function='', axes='[0]', outfile='', box='', region='', chans='', stokes='', mask='', overwrite=False, stretch=False):
r"""
Collapse image along one axis, aggregating pixel values along that axis.
[`Description`_] [`Examples`_] [`Development`_] [`Details`_]
Parameters
- imagename_ (path) - 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.
.. raw:: html
<details><summary><i> outfile != '' </i></summary>
- overwrite_ (bool=False) - Overwrite output image if it exists?
.. raw:: html
</details>
- 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.
.. raw:: html
<details><summary><i> mask != '' </i></summary>
- stretch_ (bool=False) - Stretch the mask if necessary and possible?
.. raw:: html
</details>
- stretch_ (bool=False) - Stretch the mask if necessary and possible?
.. _Description:
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.
.. rubric:: 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
:math:`\Phi^{-1}` (3/4), where :math:`\Phi^{-1}` is the
reciprocal of the quantile function. Numerically, x =
1.482602218505602. See e.g.
`here <https://en.wikipedia.org/wiki/Median_absolute_deviation#Relation_to_standard_deviation>`__).
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.
.. rubric:: General selection: *box, chans, stokes, region*
Region of interest in which the computation should be performed.
See `Image Selection
Parameters <../../notebooks/image_analysis.ipynb#Image-Selection-Parameters>`__
for details.
*mask*
On-the-fly mask to use. See section `Image
Masks <../../notebooks/image_analysis.ipynb#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:
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:
Development
No additional development details
.. _Details:
Parameter Details
Detailed descriptions of each function parameter
.. _imagename:
| ``imagename (path)`` - Name of the input image
| Default: none
| Example: imagename='ngc5921.im'
.. _function:
| ``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:
| ``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:
| ``outfile (string='')`` - Name of output CASA image. Must be specified.
| Default: none
| Example: outfile='collapsed.im'
.. _box:
| ``box (string='')`` - Rectangular region to select in direction plane.
| Default: '' (use the entire direction plane)
| Example: box="100,100,200,200"
.. _region:
| ``region (string='')`` - Region selection.
| Default: '' (use the full image)
.. _chans:
| ``chans (string='')`` - Channels to use.
| Default: '' (use all channels)
.. _stokes:
| ``stokes (string='')`` - Stokes planes to use.
| Default: '' (use all stokes planes)
.. _mask:
| ``mask (string='')`` - Mask to use.
| Default: none
.. _overwrite:
| ``overwrite (bool=False)`` - Overwrite output image if it exists?
| Default: False
| Options: False|True
.. _stretch:
| ``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.
"""
pass
```