Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/rmfit.py: 100%

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 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 

13 

14class _rmfit: 

15 """ 

16 rmfit ---- Calculate rotation measure 

17 

18 --------- parameter descriptions --------------------------------------------- 

19 

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 RETURNS bool 

32 

33 --------- examples ----------------------------------------------------------- 

34 

35  

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. 

47  

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. 

57  

58 See also the fourierrotationmeasure 

59 function for a new Fourier-based approach. 

60  

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). 

65  

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. 

74  

75 Note that no assessment of curvature (i.e. deviation 

76 from the simple linear position angle - $lambda^2$ functional form) 

77 is made. 

78  

79 Any combination of output images can be written. 

80  

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). 

86  

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. 

96  

97 Note that maxpaerr is not used to mask pixels in the output images. 

98  

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. 

102  

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. 

108  

109 EXAMPLES 

110  

111 # Calculate the rotation measure for a single polarization image 

112 rmfit(imagename="mypol.im", rm="myrm.im", rmmax=50.0) 

113  

114 # calculate the rotation measure using a set of polarization images from 

115 # different spectral windows or bands. 

116  

117 rmfit(imagename=["pol1.im", "pol2.im", "pol3.im", rm="myrm2.im", rmmax=50.0) 

118 

119 

120 """ 

121 

122 _info_group_ = """analysis""" 

123 _info_desc_ = """Calculate rotation measure""" 

124 

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 

139 

140rmfit = _rmfit( ) 

141