Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/rmfit.py: 56%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 19:10 +0000
1##################### generated by xml-casa (v2) from rmfit.xml #####################
2##################### 528fc3c83dec7253493afbc692132a37 ##############################
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_rmfit import rmfit as _rmfit_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 _rmfit:
15 """
16 rmfit ---- Calculate rotation measure
18 --------- parameter descriptions ---------------------------------------------
20 imagename Name(s) of the input image(s). Must be specified.
21 rm Output rotation measure image name. If not specified, no image is written.
22 rmerr Output rotation measure error image name. If not specified, no image is written.
23 pa0 Output position angle (degrees) at zero wavelength image name. If not specified, no image is written.
24 pa0err Output position angle (degrees) at zero wavelength error image name. If not specified, no image is written.
25 nturns Output number of turns image name. If not specified, no image is written.
26 chisq Output reduced chi squared image name. If not specified, no image is written.
27 sigma Estimate of the thermal noise. A value less than 0 means auto estimate.
28 rmfg Foreground rotation measure in rad/m/m to subtract.
29 rmmax Maximum rotation measure in rad/m/m for which to solve. IMPORTANT TO SPECIFY.
30 maxpaerr Maximum input position angle error in degrees to allow in solution determination.
31 [1;42mRETURNS[1;m bool
33 --------- examples -----------------------------------------------------------
36 PARAMETER SUMMARY
37 imagename Name(s) of the input image(s).
38 rm Output rotation measure image name. If not specified, no image is written.
39 rmerr Output rotation measure error image name. If not specified, no image is written.
40 pa0 Output position angle (degrees) at zero wavelength image name. If not specified, no image is written.
41 pa0err Output position angle (degrees) at zero wavelength error image name. If not specified, no image is written.
42 nturns Output number of turns image name. If not specified, no image is written.
43 chisq Output reduced chi squared image name. If not specified, no image is written.
44 sigma Estimate of the thermal noise. A value less than 0 means auto estimate.
45 rmfg Foreground rotation measure in rad/m/m to subtract.
46 rmmax Maximum rotation measure in rad/m/m for which to solve. IMPORTANT TO SPECIFY.
48 This task generates the rotation measure image from stokes Q and U measurements at several
49 different frequencies. You are required to specify the name of at least one image with a polarization
50 axis containing stokes Q and U planes and with a frequency axis containing more than two pixels. The
51 frequencies do not have to be equally spaced (ie the frequency coordinate can be a tabular coordinate).
52 It will work out the position angle images for you. You may also specify multiple image names, in which
53 case these images will first be concatenated along the spectral axis using ia.imageconcat(). The requirments
54 are that for all images, the axis order must be the same and the number of pixels along each axis must
55 be identical, except for the spectral axis which may differ in length between images. The spectral axis need
56 not be contiguous from one image to another.
58 See also the fourierrotationmeasure
59 function for a new Fourier-based approach.
61 Rotation measure algorithms that work robustly are few. The main
62 problem is in trying to account for the $n- pi$ ambiguity (see Leahy et
63 al, Astronomy & Astrophysics, 156, 234 or Killeen et al;
64 http://www.atnf.csiro.au/verb+~+nkilleen/rm.ps).
66 The algorithm that this task uses is that of Leahy et al. in see
67 Appendix A.1. But as in all these algorithms, the basic process is that
68 for each spatial pixel, the position angle vs frequency data is fit to
69 determine the rotation measure and the position angle at zero wavelength
70 (and associated errors). An image containing the number of $n- pi$ turns
71 that were added to the data at each spatial pixel and for which the best fit
72 was found can be written. The reduced chi-squared image for the fits can
73 also be written.
75 Note that no assessment of curvature (i.e. deviation
76 from the simple linear position angle - $lambda^2$ functional form)
77 is made.
79 Any combination of output images can be written.
81 The parameter sigma gives the thermal noise in Stokes Q and U.
82 By default it is determined automatically using the image data. But if it
83 proves to be inaccurate (maybe not many signal-free pixels), it may be
84 specified. This is used for calculating the error in the position angles (via
85 propagation of Gaussian errors).
87 The argument maxpaerr specifies the maximum allowable error in
88 the position angle that is acceptable. The default is an infinite
89 value. From the standard propagation of errors, the error in the
90 linearly polarized position angle is determined from the Stokes Q and
91 U images (at each directional pixel for each frequency). If the position angle
92 error for any pixel exceeds the specified value, the position angle at that pixel
93 is omitted from the fit. The process generates an error for the
94 fit and this is used to compute the errors in the output
95 images.
97 Note that maxpaerr is not used to mask pixels in the output images.
99 The argument rmfg is used to specify a foreground RM value. For
100 example, you may know the mean RM in some direction out of the Galaxy,
101 then including this can improve the algorithm by reducing ambiguity.
103 The parameter rmmax specifies the maximum absolute RM value that
104 should be solved for. This quite an important parameter. If you leave
105 it at the default, zero, no ambiguity handling will be
106 used. So some apriori information should be supplied; this
107 is the basic problem with rotation measure algorithms.
109 EXAMPLES
111 # Calculate the rotation measure for a single polarization image
112 rmfit(imagename="mypol.im", rm="myrm.im", rmmax=50.0)
114 # calculate the rotation measure using a set of polarization images from
115 # different spectral windows or bands.
117 rmfit(imagename=["pol1.im", "pol2.im", "pol3.im", rm="myrm2.im", rmmax=50.0)
120 """
122 _info_group_ = """analysis"""
123 _info_desc_ = """Calculate rotation measure"""
125 def __call__( self, imagename='', rm='', rmerr='', pa0='', pa0err='', nturns='', chisq='', sigma=float(-1), rmfg=float(0.0), rmmax=float(0.0), maxpaerr=float(1e30) ):
126 schema = {'imagename': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'rm': {'type': 'cStr', 'coerce': _coerce.to_str}, 'rmerr': {'type': 'cStr', 'coerce': _coerce.to_str}, 'pa0': {'type': 'cStr', 'coerce': _coerce.to_str}, 'pa0err': {'type': 'cStr', 'coerce': _coerce.to_str}, 'nturns': {'type': 'cStr', 'coerce': _coerce.to_str}, 'chisq': {'type': 'cStr', 'coerce': _coerce.to_str}, 'sigma': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'rmfg': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'rmmax': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'maxpaerr': {'type': 'cFloat', 'coerce': _coerce.to_float}}
127 doc = {'imagename': imagename, 'rm': rm, 'rmerr': rmerr, 'pa0': pa0, 'pa0err': pa0err, 'nturns': nturns, 'chisq': chisq, 'sigma': sigma, 'rmfg': rmfg, 'rmmax': rmmax, 'maxpaerr': maxpaerr}
128 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
129 _logging_state_ = _start_log( 'rmfit', [ 'imagename=' + repr(_pc.document['imagename']), 'rm=' + repr(_pc.document['rm']), 'rmerr=' + repr(_pc.document['rmerr']), 'pa0=' + repr(_pc.document['pa0']), 'pa0err=' + repr(_pc.document['pa0err']), 'nturns=' + repr(_pc.document['nturns']), 'chisq=' + repr(_pc.document['chisq']), 'sigma=' + repr(_pc.document['sigma']), 'rmfg=' + repr(_pc.document['rmfg']), 'rmmax=' + repr(_pc.document['rmmax']), 'maxpaerr=' + repr(_pc.document['maxpaerr']) ] )
130 task_result = None
131 try:
132 task_result = _rmfit_t( _pc.document['imagename'], _pc.document['rm'], _pc.document['rmerr'], _pc.document['pa0'], _pc.document['pa0err'], _pc.document['nturns'], _pc.document['chisq'], _pc.document['sigma'], _pc.document['rmfg'], _pc.document['rmmax'], _pc.document['maxpaerr'] )
133 except Exception as exc:
134 _except_log('rmfit', exc)
135 raise
136 finally:
137 task_result = _end_log( _logging_state_, 'rmfit', task_result )
138 return task_result
140rmfit = _rmfit( )