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_ (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. .. 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 (string)`` - 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