Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/imdev.py: 89%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-11-01 07:19 +0000
1##################### generated by xml-casa (v2) from imdev.xml #####################
2##################### 5c1128ffa9091f060432190f8202f67f ##############################
3from __future__ import absolute_import
4import numpy
5from casatools.typecheck import CasaValidator as _val_ctor
6_pc = _val_ctor( )
7from casatools.coercetype import coerce as _coerce
8from casatools.errors import create_error_string
9from .private.task_imdev import imdev as _imdev_t
10from casatasks.private.task_logging import start_log as _start_log
11from casatasks.private.task_logging import end_log as _end_log
12from casatasks.private.task_logging import except_log as _except_log
14class _imdev:
15 """
16 imdev ---- Create an image that can represent the statistical deviations of the input image.
18 --------- parameter descriptions ---------------------------------------------
20 imagename Input image name
21 outfile Output image file name. If left blank (the default), no image is written but a new image tool referencing the collapsed image is returned.
22 region Region selection. Default is to use the full image.
23 box Rectangular region(s) to select in direction plane. Default is to use the entire direction plane.
24 chans Channels to use. Default is to use all channels.
25 stokes Stokes planes to use. Default is to use all Stokes planes.
26 mask Mask to use. Default setting is none.
27 overwrite Overwrite (unprompted) pre-existing output file? Ignored if "outfile" is left blank.
28 stretch Stretch the mask if necessary and possible? Default value is False.
29 grid x,y grid spacing. Array of exactly two positive integers.
30 anchor x,y anchor pixel location. Either "ref" to use the image reference pixel, or an array of exactly two integers.
31 xlength Either x coordinate length of box, or diameter of circle. Circle is used if ylength is empty string.
32 ylength y coordinate length of box. Use a circle if ylength is empty string.
33 interp Interpolation algorithm to use. One of "nearest", "linear", or "cubic". Minimum match supported.
34 stattype Statistic to compute. See full description for supported statistics.
35 statalg Statistics computation algorithm to use. Supported values are "chauvenet" and "classic", Minimum match is supported.
36 zscore For chauvenet, this is the target maximum number of standard deviations data may have to be included. If negative, use Chauvenet"s criterion. Ignored if algorithm is not "chauvenet".
37 maxiter For chauvenet, this is the maximum number of iterations to attempt. Iterating will stop when either this limit is reached, or the zscore criterion is met. If negative, iterate until the zscore criterion is met. Ignored if algortihm is not "chauvenet".
38 [1;42mRETURNS[1;m bool
40 --------- examples -----------------------------------------------------------
43 This application creates an image that reflects the statistics of the input image. The output image has
44 the same dimensions and coordinate system as the (selected region in) input image. The grid parameter
45 describes how many pixels apart "grid" pixels are. Statistics are computed around each grid pixel. Grid
46 pixels are limited to the direction plane only; independent statistics are computed for each direction plane
47 (ie at each frequency/stokes pixel should the input image happen to have such additional axes). Using the
48 xlength and ylength parameters, one may specify either a rectangular or circular region around each grid
49 point that defines which surrounding pixels are used in the statistic computation for individual grid points.
50 If the ylength parameter is the empty string, then a circle of diameter provided by xlength centered on
51 the grid point is used. If ylength is not empty, then a rectangular box of dimensions xlength x ylength centered
52 on the grid pixel is used. These two parameters may be specified in pixels, using either numerical values or
53 valid quantities with "pix" as the unit (eg "4pix"). Otherwise, they must be specified as valid angular
54 quantities, with recognized units (eg "4arcsec"). As with other region selections in CASA, full pixels are
55 included in the computation even if the specified region includes only a fraction of that pixel. BEWARE OF
56 MACHINE PRECISION ISSUES, because you may get a smaller number of pixels included in a region than you
57 expect if you specify, eg, an integer number of pixels. In such cases, you probably want to specify that
58 number plus a small epsilon value (eg "2.0001pix" rather than "2pix") to mitigate machine precision issues
59 when computing region extents.
61 The output image is formed by putting the statistics calculated at each grid point at the corresponding
62 grid point in the output image. Interpolation of these output values is then used to compute values at
63 non-grid-point pixels. The user may specify which interpolation algorithm to use for this computation
64 using the interp parameter.
66 The input image pixel mask is copied to the output image. If interpolation is performed, output pixels are
67 masked where the interpolation fails.
69 ANCHORING THE GRID
71 The user may choose at which pixel to "anchor" the grid. For example, if one specifies grid=[4,4] and
72 anchor=[0,0], grid points will be located at pixels [0,0], [0,4], [0,8] ... [4,0], [4,4], etc. This
73 is exactly the same grid that would be produced if the user specified anchor=[4,4] or anchor=[20,44].
74 If the user specifies anchor=[1, 2] and grid=[4,4], then the grid points will be at pixels [1,2], [5,2],
75 [9,2]... [5,2], [5,6], etc. and the resulting grid is the same as it would be if the user specified eg
76 anchor=[9,10] or anchor=[21, 18]. The value "ref", which is the default, indicates that the reference
77 pixel of the input image should be used to anchor the grid. The x and y values of this pixel will be
78 rounded to the nearest integer if necessary.
80 SUPPORTED STATISTICS AND STATISTICS ALGORITHMS
82 One may specify which statistic should be represented using the stattype parameter. The following values
83 are recognized (minimum match supported):
85 iqr inner quartile range (q3 - q1)
86 max maximum
87 mean mean
88 medabsdevmed, madm median absolute deviation from the median
89 median median
90 min minimum
91 npts number of points
92 q1 first quartile
93 q3 third quartile
94 rms rms
95 sigma, std standard deviation
96 sumsq sum of squares
97 sum sum
98 var variance
99 xmadm median absolute deviation from the median multipied by x, where x is the reciprocal of Phi^-1(3/4),
100 where Phi^-1 is the reciprocal of the quantile function. Numerically, x = 1.482602218505602. See, eg,
101 https://en.wikipedia.org/wiki/Median_absolute_deviation#Relation_to_standard_deviation
103 Using the statalg parameter, one may also select whether to use the Classical or Chauvenet/ZScore statistics algorithm to
104 compute the desired statistic (see the help for ia.statistics() or imstat for a full description of these algorithms).
106 # compute standard deviations in circles of diameter 10arcsec around
107 # grid pixels spaced every 4 x 5 pixels and anchored at pixel [30, 40],
108 # and use linear interpolation to compute values at non-grid-pixels
109 imdev("my.im", "sigma.im", grid=[4, 5], anchor=[30, 40], xlength="10arcsec", stattype="sigma", interp="lin", statalg="cl")
111 # compute median of the absolute deviations from the median values using
112 # the z-score/Chauvenet algorithm, by fixing the maximum z-score to determine outliers to 5.
113 # Use cubic interpolation to compute values for non-grid-point pixels. Use a rectangular region
114 # of dimensions 5arcsec x 20arcsec centered on each grid point as the region in which to include
115 # pixels for the computation of stats for that grid point.
116 imdev("my.im", "madm.im", grid=[4, 5], anchor=[30, 40], xlength="5arcsec", ylength="20arcsec, stattype="madm", interp="cub", statalg="ch", zscore=5)
119 """
121 _info_group_ = """analysis"""
122 _info_desc_ = """Create an image that can represent the statistical deviations of the input image."""
124 def __call__( self, imagename='', outfile='', region='', box='', chans='', stokes='', mask='', overwrite=False, stretch=False, grid=[ int(1),int(1) ], anchor='ref', xlength='1pix', ylength='1pix', interp='cubic', stattype='sigma', statalg='classic', zscore=float(-1), maxiter=int(-1) ):
125 schema = {'imagename': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'outfile': {'type': 'cStr', 'coerce': _coerce.to_str}, 'region': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cDict'}]}, 'box': {'type': 'cStr', 'coerce': _coerce.to_str}, 'chans': {'type': 'cStr', 'coerce': _coerce.to_str}, 'stokes': {'type': 'cStr', 'coerce': _coerce.to_str}, 'mask': {'type': 'cStr', 'coerce': _coerce.to_str}, 'overwrite': {'type': 'cBool'}, 'stretch': {'type': 'cBool'}, 'grid': {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, 'anchor': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}]}, 'xlength': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cInt'}]}, 'ylength': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cInt'}]}, 'interp': {'type': 'cStr', 'coerce': _coerce.to_str}, 'stattype': {'type': 'cStr', 'coerce': _coerce.to_str}, 'statalg': {'type': 'cStr', 'coerce': _coerce.to_str}, 'zscore': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'maxiter': {'type': 'cInt'}}
126 doc = {'imagename': imagename, 'outfile': outfile, 'region': region, 'box': box, 'chans': chans, 'stokes': stokes, 'mask': mask, 'overwrite': overwrite, 'stretch': stretch, 'grid': grid, 'anchor': anchor, 'xlength': xlength, 'ylength': ylength, 'interp': interp, 'stattype': stattype, 'statalg': statalg, 'zscore': zscore, 'maxiter': maxiter}
127 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
128 _logging_state_ = _start_log( 'imdev', [ 'imagename=' + repr(_pc.document['imagename']), 'outfile=' + repr(_pc.document['outfile']), 'region=' + repr(_pc.document['region']), 'box=' + repr(_pc.document['box']), 'chans=' + repr(_pc.document['chans']), 'stokes=' + repr(_pc.document['stokes']), 'mask=' + repr(_pc.document['mask']), 'overwrite=' + repr(_pc.document['overwrite']), 'stretch=' + repr(_pc.document['stretch']), 'grid=' + repr(_pc.document['grid']), 'anchor=' + repr(_pc.document['anchor']), 'xlength=' + repr(_pc.document['xlength']), 'ylength=' + repr(_pc.document['ylength']), 'interp=' + repr(_pc.document['interp']), 'stattype=' + repr(_pc.document['stattype']), 'statalg=' + repr(_pc.document['statalg']), 'zscore=' + repr(_pc.document['zscore']), 'maxiter=' + repr(_pc.document['maxiter']) ] )
129 task_result = None
130 try:
131 task_result = _imdev_t( _pc.document['imagename'], _pc.document['outfile'], _pc.document['region'], _pc.document['box'], _pc.document['chans'], _pc.document['stokes'], _pc.document['mask'], _pc.document['overwrite'], _pc.document['stretch'], _pc.document['grid'], _pc.document['anchor'], _pc.document['xlength'], _pc.document['ylength'], _pc.document['interp'], _pc.document['stattype'], _pc.document['statalg'], _pc.document['zscore'], _pc.document['maxiter'] )
132 except Exception as exc:
133 _except_log('imdev', exc)
134 raise
135 finally:
136 task_result = _end_log( _logging_state_, 'imdev', task_result )
137 return task_result
139imdev = _imdev( )