Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/imagepol.py: 59%
82 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 17:39 +0000
1##################### generated by xml-casa (v2) from imagepol.xml ##################
2##################### 3b7437629b45930681a8977ca52048f2 ##############################
3from __future__ import absolute_import
4from .__casac__.imagepol import imagepol as _imagepol
6from .errors import create_error_string
7from .typecheck import CasaValidator as _validator
8_pc = _validator( )
9from .coercetype import coerce as _coerce
10from .image import image as _wrap_image
12class imagepol:
13 _info_group_ = """images"""
14 _info_desc_ = """Polarimetric analysis of images"""
15 ### self
16 def __init__(self, *args, **kwargs):
17 """The constructor takes an image as its input. This can be specified as
18 either the name of a disk file, or you can give a pre-existing Image
19 tool. If you give a disk file name, the disk image file may
20 be in casa, fits or Miriad format.
22 The input image must have a Stokes axis. The exact collection of Stokes
23 that the image has, determines what the Imagepol tool can compute.
24 Stokes I, Q, U, and V refer to total intensity, two components of linear
25 polarization, and circular polatization, respectively. Therefore, if
26 you ask for linear polarization and the image only has Stokes I and V,
27 you will get an error.
29 The input image may contain data at many frequencies. For example, the
30 image may be a 4D image with axes RA, DEC, Stokes and Frequency (order
31 not important) where the Frequency axis is regularly sampled. However,
32 the image may also contain many frequencies at irregular intervals.
33 Such an image may be created with the Image tool constructor called
34 imageconcat. It enables you to concatenate
35 images along an axis, and it allows irregular coordinate values along that
36 axis.
37 """
38 self._swigobj = kwargs.get('swig_object',None)
39 if self._swigobj is None:
40 self._swigobj = _imagepol()
42 def imagepoltestimage(self, outfile='imagepol.iquv', rm=[ float(0.0) ], pa0=float(0.0), sigma=float(0.01), nx=int(32), ny=int(32), nf=int(32), f0=float(1.4e9), bw=float(128.0e6)):
43 """This function can be used to generate a test image and then
44 attach the Imagepol tool to it.
46 The test image is 4-dimensional (RA, DEC, Stokes and Frequency). The
47 Stokes axis holds I,Q,U and V. The source is just a constant I (if you
48 don't add noise all spatial pixels will be identical) and V. Q and U
49 vary with frequency according to the specified Rotation Measure
50 components (no attempt to handle bandwidth smearing within channels is
51 made). The actual values of I,Q,U, and V are chosen arbitrarily
52 otherwise (could be added as arguments if desired).
54 You can use this image, in particular, to explore the Rotation Measure
55 algorithms in functions rotationmeasure and
56 fourierrotationmeasure.
58 If you don't specify the Rotation Measure, then it is chosen for you so
59 that there is no position angle ambiguity between adjacent channels
60 (the value will be sent to the Logger).
62 The noise added to the image is specified as a fraction of the total
63 intensity (constant). Gaussian noise with a standard deviation of
64 {stfaf sigma * $I_{max}$} is then added to the image.
65 """
66 return self._swigobj.imagepoltestimage(outfile, rm, pa0, sigma, nx, ny, nf, f0, bw)
68 def complexlinpol(self, outfile):
69 """This function produces
70 the complex linear polarization; $Q+iU$ and writes
71 it to a disk image file.
73 The Image tool cannot yet handle Complex
74 images. You must therefore write the Complex image to disk. The
75 Viewer can display Complex images. Also the
76 Table tool can access Complex images.
77 """
78 return self._swigobj.complexlinpol(outfile)
80 def complexfraclinpol(self, outfile):
81 """This function produces
82 the complex fractional linear polarization; $(Q+iU)/I$ and writes
83 it to a disk image file.
85 The Image tool cannot yet handle Complex
86 images. You must therefore write the Complex image to disk. The
87 Viewer can display Complex images. Also the
88 Table tool can access Complex images.
89 """
90 return self._swigobj.complexfraclinpol(outfile)
92 def depolratio(self, infile, debias=False, clip=float(10.0), sigma=float(-1), outfile=''):
93 """This function returns the linear
94 depolarization ratio computed from two frequencies; this is the ratio of
95 the fractional linear polarization at the two frequencies. Generally
96 this is done when you have generated two images, each at a different frequency
97 (continuum work). Thus if the fractional linear polarization images are
98 $m_{nu 1}$ and $m_{nu 2}$ then the depolarization ratio is
99 $m_{nu 1}/ m_{nu 2}$.
101 This function operates with two images; the first (at frequency $nu 1$)
102 is the one attached to your Imagepol tool. The second (at
103 frequency $nu 2$) is supplied via the argument {stfaf infile}, which
104 is a String holding the name of the
105 imagefile.
107 In generating the depolarization ratio, you may optionally debias the
108 linearly polarized intensity. This requires the standard deviation of
109 the thermal noise. You can either supply it if you know it, or it will
110 be worked out for you with outliers from the mean clipped at the
111 specified level.
113 You can get the depolarization ratio error image with function
114 sigmadepolratio.
115 """
116 return _wrap_image(swig_object=self._swigobj.depolratio(infile, debias, clip, sigma, outfile))
118 def close(self):
119 """This function closes the imagepol tool. This means that it detaches
120 the tool from its imagefile (flushing all the changes first). The
121 imagepol tool is ``null'' after this change (it is not destroyed) and
122 calling any toolfunction other than open will result in an
123 error.
124 """
125 return self._swigobj.close()
127 def done(self):
128 """This function is the same as close().
129 """
130 return self._swigobj.done()
132 def fourierrotationmeasure(self, complex='', amp='', pa='', real='', imag='', zerolag0=False):
133 """This function will only work if
134 you attach the Imagepol tool (using open) to an image containing
135 Stokes Q and U, and a regular frequency axis. It Fourier transforms
136 the complex linear polarization (Q+iU) over the spectral axis to the
137 rotation measure axis. Thus, if your input image contained
138 RA/DEC/Stokes/Frequency, the output image would be
139 RA/DEC/RotationMeasure. The Rotation Measure axis has as many pixels
140 as the spectral axis.
142 This method enables you to see the polarization as a function of
143 Rotation Meausure. Its main use is when searching for large RMs. See
144 Killeen, Fluke, Zhao and Ekers (1999, preprint) for a description of
145 this method (or http://www.atnf.csiro.au/verb+~+nkilleen/rm.ps) and its
146 advantages over the traditional method
147 (rotationmeasure) of
148 extracting the Rotation Measure.
150 Although you can write out the complex polarization image with the
151 argument {stfaf complex}, you can't do much with it because Image
152 tools cannot handle complex images. Hence you can
153 also write out the complex linear polarization image in any or all of
154 the other forms.
156 The argument {stfaf zerolag0} allows you to force the zero lag (or
157 central bin) of the Rotation Measure spectrum to zero (effectively by
158 subtracting the mean of Q and U from the Q and U images). This may
159 avoid Gibbs phenomena from any strong low Rotation Measure signal which
160 would normally fall into the central bin.
161 """
162 return self._swigobj.fourierrotationmeasure(complex, amp, pa, real, imag, zerolag0)
164 def fraclinpol(self, debias=False, clip=float(10.0), sigma=float(-1), outfile=''):
165 """This function
166 returns the fractional linear polarization; $sqrt{(Q^2+U^2)}/I$.
168 You may optionally debias the polarized intensity. This requires the
169 standard deviation of the thermal noise. You can either supply it if
170 you know it, or it will be worked out for you with outliers from the
171 mean clipped at the specified level.
172 """
173 return _wrap_image(swig_object=self._swigobj.fraclinpol(debias, clip, sigma, outfile))
175 def fractotpol(self, debias=False, clip=float(10.0), sigma=float(-1), outfile=''):
176 """This function
177 returns the fractional linear polarization; $sqrt{(Q^2+U^2+V^2)}/I$.
179 You may optionally debias the polarized intensity. This requires the
180 standard deviation of the thermal noise. You can either supply it if
181 you know it, or it will be worked out for you with outliers from the
182 mean clipped at the specified level.
184 If your image contains only Q and U, or only V, then just
185 those components contribute to the total polarized intensity.
186 """
187 return _wrap_image(swig_object=self._swigobj.fractotpol(debias, clip, sigma, outfile))
189 def linpolint(self, debias=False, clip=float(10.0), sigma=float(-1), outfile='', region='', mask='', stretch=False):
190 """This application returns the linearly polarized intensity; $sqrt{(Q^2+U^2)}$.
192 The linearly polarized intensity may optionally be debiased (if debias=True).
193 This requires an estimate of the thermal noise level (sigma). The resulting
194 image will be computed using
196 $sqrt{(Q^2 + U^2 - sigma^2)}$
198 If the specified value of sigma is positive, that is the value that will
199 be used for debiasing. If it is not, the value used for sigma is computed
200 using the following algorithm:
202 1. First, a stokes plane(s) is chosen on which the sigma computation is performed.
203 If the V plane exists, that is used to compute sigma. If not, then the value of
204 sigma is computed to be the average of the sigma values of the Q and U planes.
206 2. For the relevant plane(s), the sigma value is computed for unmasked pixel values
207 which lie within +/- (clip * stddev) values of the mean for that plane, where the mean
208 and stddev (the standard deviation) are computed by using all unmasked pixel values
209 in the relevant plane. In this way, outliers (eg pixels due to possible
210 astronomical signals) are excluded in the computation of sigma.
212 In the output image, pixels for which the expression inside the square root is
213 negative are masked, and their values are set to zero.
215 If a region and/or mask is specified, debias=True and sigma is not positive so
216 that the value of sigma is determined using the algorithm above, the region and mask
217 are applied first to the plane(s) from which the value of sigma is determined and
218 then sigma is computed.
219 """
220 return _wrap_image(swig_object=self._swigobj.linpolint(debias, clip, sigma, outfile, region, mask, stretch))
222 def linpolposang(self, outfile='', region='', mask='', stretch=False):
223 """This function returns the linearly polarized position angle image 0.5*arctan(U/Q) in degrees.
224 The output image will not have a restoring beam, even if the input image does.
225 """
226 return _wrap_image(swig_object=self._swigobj.linpolposang(outfile, region, mask, stretch))
228 def makecomplex(self, complex, real='', imag='', amp='', phase=''):
229 """This function generates a Complex imagefile from either
230 a real and imaginary, or an amplitude and phase pair of images.
231 If you give a linear position angle image for the phase,
232 it will be multipled by two before the real and imaginary
233 parts are formed.
234 """
235 return self._swigobj.makecomplex(complex, real, imag, amp, phase)
237 def open(self, image={ }):
238 """Before polarimetric analysis can commence, an imagefile must be
239 attached to the imagepol tool using the open function. Also, use this
240 function when you are finished analyzing the current imagefile and
241 want to attach to another one. This function detaches the imagetool
242 from the current imagefile, if one exists, and reattaches it (opens)
243 to the new imagefile.
245 The input image file may be in native casa, fits, or Miriad
246 format. Look htmlref{here}{IMAGES:FOREIGNIMAGES} for more
247 information on foreign images.
249 The input image must have a Stokes axis. The exact collection of
250 Stokes that the image has, determines what the Imagepol tool can
251 compute. Stokes I, Q, U, and V refer to total intensity, two
252 components of linear polarization, and circular polatization,
253 respectively. Therefore, if you ask for linear polarization and the
254 image only has Stokes I and V, you will get an error.
256 The input image may contain data at many frequencies. For example, the
257 image may be a 4D image with axes RA, DEC, Stokes and Frequency (order
258 not important) where the Frequency axis is regularly sampled. However,
259 the image may also contain many frequencies at irregular
260 intervals. Such an image may be created with the Image tool function
261 imageconcat. It enables you to concatenate images along an axis, and
262 it allows irregular coordinate values along that axis.
263 """
264 return self._swigobj.open(image)
266 def pol(self, which, debias=False, clip=float(10.0), sigma=float(-1), outfile=''):
267 """This function just packages the other specific polarization
268 functions into one where you specify an operation with the
269 argument {stfaf which} (can be useful for scripts).
270 This argument can take the values:
272 begin{itemize}
273 item 'lpi' - linearly polarized intensity (function
274 linpolint)
276 item 'tpi' - total polarized intensity (function
277 totpolint)
279 item 'lppa' linearly polarized position angle (function
280 linpolposang)
282 item 'flp' - fractional linear polarization (function
283 fraclinpol)
285 item 'ftp' - fractional total polarized intensity (function
286 fractotpol)
288 end{itemize}
289 """
290 return _wrap_image(swig_object=self._swigobj.pol(which, debias, clip, sigma, outfile))
292 def rotationmeasure(self, rm='', rmerr='', pa0='', pa0err='', nturns='', chisq='', sigma=float(-1), rmfg=float(0.0), rmmax=float(0.0), maxpaerr=float(1e30), plotter='', nx=int(5), ny=int(5)):
293 """This function generates the rotation
294 measure image from a collection of different frequencies. It will only
295 work if the Imagepol tool is attached to an image containing
296 Stokes $Q$ and $U$, and a frequency axis (regular or irregular) with at
297 least 2 pixels. It will work out the position angle images for you.
299 See also the fourierrotationmeasure
300 function for a new Fourier-based approach.
302 Rotation Measure algorithms that work robustly are not common. The main
303 problem is in trying to account for the $n- pi$ ambiguity (see Leahy et
304 al, Astronomy & Astrophysics, 156, 234 or Killeen et al;
305 http://www.atnf.csiro.au/verb+~+nkilleen/rm.ps).
307 The algorithm that this function uses is that of Leahy et al. (see Appendix A.1). But as in all
308 these algorithms, the basic process is that for each spatial pixel, a
309 vector of position angles (i.e. at the different frequencies) is fit to
310 determine the rotation measure and the position angle at zero wavelength
311 (and their errors). An image containing
312 the number of $n- pi$ turns that were added to the data
313 at each spatial pixel and for which the best fit was found can be written.
314 The reduced chi-squared image for the fits can also be written.
316 Note that no assessment of curvature (i.e. deviation
317 from the simple linear position angle - $lambda^2$ functional form)
318 is made.
320 Any combination of output images can be written.
322 The argument {stfaf sigma} gives the thermal noise in Stokes Q and U.
323 By default it is determined automatically using the image data. But if it proves
324 to be inaccurate (maybe not many signal-free pixels), it may be specified.
325 This is used for calculating the error in the
326 position angles (propagation of Gaussian errors).
328 The argument {stfaf maxpaerr} specifies the maximum allowable error in
329 the position angle that is acceptable. The default is an infinite
330 value. From the standard propagation of errors, the error in the
331 linearly polarized position angle is determined from the Stokes $Q$ and
332 $U$ images (at each spatial pixel for each frequency). At each spatial
333 pixel we do a fit to the position angle vector (i.e. at the different
334 frequencies) to determine the rotation measure. If the position angle
335 error for any pixel in the vector exceeds the specified value, it is
336 dropped from the fit. The process generates an error for the
337 fit and this is used to compute the errors in the output
338 images.
340 Note that {stfaf maxpaerr} is {it not} used to specify that any pixel
341 for which the output position angle error exceeds this value
342 should be masked out.
344 The argument {stfaf rmfg} is used to specify a foreground RM value. For
345 example, you may know the mean RM in some direction out of the Galaxy,
346 then including this can aid the algorithm by reducing ambiguity.
348 The argument {stfaf rmmax} specifies the maximum absolute RM that
349 should be solved for. This quite an important parameter. If you leave
350 it at the default, zero, no ambiguity handling will be
351 used. So some apriori information should be supplied; this
352 is the basic problem with rotation measure algorithms.
353 """
354 return self._swigobj.rotationmeasure(rm, rmerr, pa0, pa0err, nturns, chisq, sigma, rmfg, rmmax, maxpaerr, plotter, nx, ny)
356 def sigma(self, clip=float(10.0)):
357 """This function returns the standard deviation from V, Q&U or I in that
358 order of precedence. It is attempting to give you the best estimate of
359 the thermal noise it can from the data. Outliers from the mean are
360 clipped at the specified level.
361 """
362 return self._swigobj.sigma(clip)
364 def sigmadepolratio(self, infile, debias=False, clip=float(10.0), sigma=float(-1), outfile=''):
365 """This function returns the error
366 in the linear depolarization ratio computed from two frequencies; this
367 is the ratio of the fractional linear polarization at the two
368 frequencies. Generally this is done when you have generated two
369 images, each at a different frequency (continuum work). Thus if the
370 fractional linear polarzation images are $m1$ and $m2$ then the
371 depolarization ratio is $m1/m2$.
373 This function operates with two images; the first is attached
374 to the Imagepol tool. The second is supplied via the
375 argument {stfaf infile}, which is a String
376 holding the name of the imagefile.
378 In generating the depolarization ratio, and hence its error, you may
379 optionally debias the linearly polarized intensity. This requires the
380 standard deviation of the thermal noise. You can either supply it if
381 you know it, or it will be worked out for you with outliers from the
382 mean clipped at the specified level.
384 You can get the depolarization ratio image with function
385 depolratio.
386 """
387 return _wrap_image(swig_object=self._swigobj.sigmadepolratio(infile, debias, clip, sigma, outfile))
389 def sigmafraclinpol(self, clip=float(10.0), sigma=float(-1), outfile=''):
390 """This function returns the
391 error (standard deviation) of the fractional linear polarization.
392 This result comes from standard propagation of errors. The result is
393 an on-the-fly Image tool as the error is signal-to-noise ratio
394 dependent.
396 This function requires the standard deviation of the thermal noise. You
397 can either supply it if you know it, or it will be worked out for you
398 with outliers from the mean clipped at the specified level.
399 """
400 return _wrap_image(swig_object=self._swigobj.sigmafraclinpol(clip, sigma, outfile))
402 def sigmafractotpol(self, clip=float(10.0), sigma=float(-1), outfile=''):
403 """This function returns the
404 error (standard deviation) of the fractional total polarization. This
405 result comes from standard propagation of errors. The result is an
406 on-the-fly Image tool as the error is signal-to-noise ratio dependent.
408 This function requires the standard deviation of the thermal noise. You
409 can either supply it if you know it, or it will be worked out for you
410 with outliers from the mean clipped at the specified level.
411 """
412 return _wrap_image(swig_object=self._swigobj.sigmafractotpol(clip, sigma, outfile))
414 def sigmalinpolint(self, clip=float(10.0), sigma=float(-1), outfile=''):
415 """This function returns the error (standard
416 deviation) of the linearly polarized intensity; $sqrt{(Q^2+U^2)}$.
417 This result comes from standard propagation of statistical errors.
418 The result is a float as the error is not signal-to-noise
419 ratio dependent
421 This function requires the standard deviation of the thermal noise. You
422 can either supply it if you know it, or it will be worked out for you
423 with outliers from the mean clipped at the specified level.
424 """
425 return self._swigobj.sigmalinpolint(clip, sigma, outfile)
427 def sigmalinpolposang(self, clip=float(10.0), sigma=float(-1), outfile=''):
428 """This function returns the
429 error (standard deviation) of the linearly polarized position angle
430 ($0.5 tan^{-1}(U/Q)$$sqrt{(Q^2+U^2)}$) in degrees. This result
431 comes from standard propagation of errors. The result is an
432 on-the-fly Image tool as the error is signal-to-noise ratio dependent.
434 This function requires the standard deviation of the thermal noise. You
435 can either supply it if you know it, or it will be worked out for you
436 with outliers from the mean clipped at the specified level.
437 """
438 return _wrap_image(swig_object=self._swigobj.sigmalinpolposang(clip, sigma, outfile))
440 def sigmastokes(self, which, clip=float(10.0)):
441 """This function returns the standard
442 deviation of the noise for the specified Stokes. Outliers from the mean
443 are clipped at the specified level.
444 """
445 return self._swigobj.sigmastokes(which, clip)
447 def sigmastokesi(self, clip=float(10.0)):
448 """This function returns the standard deviation of the noise for the
449 Stokes I data. Outliers from the mean are clipped at the specified
450 level.
451 """
452 return self._swigobj.sigmastokesi(clip)
454 def sigmastokesq(self, clip=float(10.0)):
455 """This function returns the standard deviation of the noise for the
456 Stokes Q data. Outliers from the mean are clipped at the specified
457 level.
458 """
459 return self._swigobj.sigmastokesq(clip)
461 def sigmastokesu(self, clip=float(10.0)):
462 """This function returns the standard
463 deviation of the noise for the Stokes U data. Outliers from the mean
464 are clipped at the specified level.
465 """
466 return self._swigobj.sigmastokesu(clip)
468 def sigmastokesv(self, clip=float(10.0)):
469 """This function returns the standard
470 deviation of the noise for the Stokes V data. Outliers from the mean
471 are clipped at the specified level.
472 """
473 return self._swigobj.sigmastokesv(clip)
475 def sigmatotpolint(self, clip=float(10.0), sigma=float(-1)):
476 """This function returns the error (standard
477 deviation) of the total polarized intensity; $sqrt{(Q^2+U^2+V^2)}$.
478 This result comes from standard propagation of statistical errors.
479 The result is a float as the error is not signal-to-noise
480 ratio dependent
482 This function requires the standard deviation of the thermal noise. You
483 can either supply it if you know it, or it will be worked out for you
484 with outliers from the mean clipped at the specified level.
485 """
486 return self._swigobj.sigmatotpolint(clip, sigma)
488 def stokes(self, which, outfile=''):
489 """This function returns an on-the-fly image tool containing the
490 specified Stokes only. This interface can be useful for scripts.
491 """
492 return _wrap_image(swig_object=self._swigobj.stokes(which, outfile))
494 def stokesi(self, outfile=''):
495 """This function returns an on-the-fly image tool containing Stokes I only.
496 """
497 return _wrap_image(swig_object=self._swigobj.stokesi(outfile))
499 def stokesq(self, outfile=''):
500 """This function returns an on-the-fly image tool containing Stokes Q only.
501 """
502 return _wrap_image(swig_object=self._swigobj.stokesq(outfile))
504 def stokesu(self, outfile=''):
505 """This function returns an on-the-fly image tool containing Stokes U only.
506 """
507 return _wrap_image(swig_object=self._swigobj.stokesu(outfile))
509 def stokesv(self, outfile=''):
510 """This function returns an on-the-fly image tool containing Stokes V only.
511 """
512 return _wrap_image(swig_object=self._swigobj.stokesv(outfile))
514 def summary(self):
515 """This function just lists a summary of the Imagepol tool to the logger.
516 Currently it just summarizes the image to which the tool is attached.
517 """
518 return self._swigobj.summary()
520 def totpolint(self, debias=False, clip=float(10.0), sigma=float(-1), outfile='', region='', mask='', stretch=False):
521 """This application returns the total polarized intensity;
523 $sqrt{( Q^2+ U^2+ V^2)}$.
525 If the image contains only Q and U, or only V, then just
526 those components contribute to the total polarized intensity.
528 The polarized intensity may optionally be debiased (if debias=True).
529 This requires an estimate of the thermal noise level (sigma).
530 The resulting image will be computed using
532 $sqrt{(Q^2 + U^2 + V^2 - sigma^2)}$
534 If the specified value of sigma is positive, that is the value that will
535 be used for debiasing. If it is not, the value used for sigma is computed
536 using the following algorithm:
538 1. First, a stokes plane(s) is chosen on which the sigma computation is performed.
539 If the V plane exists, that is used to compute sigma. If not, then the value of
540 sigma is computed to be the average of the sigma values of the Q and U planes.
542 2. For the relevant plane(s), the sigma value is computed for unmasked pixel values
543 which lie within +/- (clip * stddev) values of the mean for that plane, where the mean
544 and stddev (the standard deviation) are computed by using all unmasked pixel values
545 in the relevant plane. In this way, outliers (eg pixels due to possible
546 astronomical signals) are excluded in the computation of sigma.
548 In the output image, pixels for which the expression inside the square root is
549 negative are masked, and their values are set to zero.
551 If a region and/or mask is specified, debias=True and sigma is not positive so
552 that the value of sigma is determined using the algorithm above, the region and mask
553 are applied first to the plane(s) from which the value of sigma is determined and
554 then sigma is computed.
555 """
556 return _wrap_image(swig_object=self._swigobj.totpolint(debias, clip, sigma, outfile, region, mask, stretch))