Coverage for /wheeldirectory/casa-6.7.0-11-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/__casac__/imagepol.py: 42%
160 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-23 15:54 +0000
1# This file was automatically generated by SWIG (http://www.swig.org).
2# Version 3.0.12
3#
4# Do not make changes to this file unless you know what you are doing--modify
5# the SWIG interface file instead.
7from sys import version_info as _swig_python_version_info
8if _swig_python_version_info >= (2, 7, 0):
9 def swig_import_helper():
10 import importlib
11 pkg = __name__.rpartition('.')[0]
12 mname = '.'.join((pkg, '_imagepol')).lstrip('.')
13 try:
14 return importlib.import_module(mname)
15 except ImportError:
16 return importlib.import_module('_imagepol')
17 _imagepol = swig_import_helper()
18 del swig_import_helper
19elif _swig_python_version_info >= (2, 6, 0):
20 def swig_import_helper():
21 from os.path import dirname
22 import imp
23 fp = None
24 try:
25 fp, pathname, description = imp.find_module('_imagepol', [dirname(__file__)])
26 except ImportError:
27 import _imagepol
28 return _imagepol
29 try:
30 _mod = imp.load_module('_imagepol', fp, pathname, description)
31 finally:
32 if fp is not None:
33 fp.close()
34 return _mod
35 _imagepol = swig_import_helper()
36 del swig_import_helper
37else:
38 import _imagepol
39del _swig_python_version_info
41try:
42 _swig_property = property
43except NameError:
44 pass # Python < 2.2 doesn't have 'property'.
46try:
47 import builtins as __builtin__
48except ImportError:
49 import __builtin__
51def _swig_setattr_nondynamic(self, class_type, name, value, static=1):
52 if (name == "thisown"):
53 return self.this.own(value)
54 if (name == "this"):
55 if type(value).__name__ == 'SwigPyObject':
56 self.__dict__[name] = value
57 return
58 method = class_type.__swig_setmethods__.get(name, None)
59 if method:
60 return method(self, value)
61 if (not static):
62 if _newclass:
63 object.__setattr__(self, name, value)
64 else:
65 self.__dict__[name] = value
66 else:
67 raise AttributeError("You cannot add attributes to %s" % self)
70def _swig_setattr(self, class_type, name, value):
71 return _swig_setattr_nondynamic(self, class_type, name, value, 0)
74def _swig_getattr(self, class_type, name):
75 if (name == "thisown"):
76 return self.this.own()
77 method = class_type.__swig_getmethods__.get(name, None)
78 if method:
79 return method(self)
80 raise AttributeError("'%s' object has no attribute '%s'" % (class_type.__name__, name))
83def _swig_repr(self):
84 try:
85 strthis = "proxy of " + self.this.__repr__()
86 except __builtin__.Exception:
87 strthis = ""
88 return "<%s.%s; %s >" % (self.__class__.__module__, self.__class__.__name__, strthis,)
90try:
91 _object = object
92 _newclass = 1
93except __builtin__.Exception:
94 class _object:
95 pass
96 _newclass = 0
98class imagepol(_object):
99 """Proxy of C++ casac::imagepol class."""
101 __swig_setmethods__ = {}
102 __setattr__ = lambda self, name, value: _swig_setattr(self, imagepol, name, value)
103 __swig_getmethods__ = {}
104 __getattr__ = lambda self, name: _swig_getattr(self, imagepol, name)
105 __repr__ = _swig_repr
107 def __init__(self):
108 """__init__(self) -> imagepol"""
109 this = _imagepol.new_imagepol()
110 try:
111 self.this.append(this)
112 except __builtin__.Exception:
113 self.this = this
115 def imagepoltestimage(self, *args, **kwargs):
116 """
117 imagepoltestimage(self, _outfile, _rm, _pa0, _sigma, _nx, _ny, _nf, _f0, _bw) -> bool
121 Summary:
122 Attach the Imagepol tool to a test image file
124 Description:
128 This function can be used to generate a test image and then
129 attach the Imagepol tool to it.
131 The test image is 4-dimensional (RA, DEC, Stokes and Frequency). The
132 Stokes axis holds I,Q,U and V. The source is just a constant I (if you
133 don't add noise all spatial pixels will be identical) and V. Q and U
134 vary with frequency according to the specified Rotation Measure
135 components (no attempt to handle bandwidth smearing within channels is
136 made). The actual values of I,Q,U, and V are chosen arbitrarily
137 otherwise (could be added as arguments if desired).
139 You can use this image, in particular, to explore the Rotation Measure
140 algorithms in functions rotationmeasure and
141 fourierrotationmeasure.
143 If you don't specify the Rotation Measure, then it is chosen for you so
144 that there is no position angle ambiguity between adjacent channels
145 (the value will be sent to the Logger).
147 The noise added to the image is specified as a fraction of the total
148 intensity (constant). Gaussian noise with a standard deviation of
149 {stfaf sigma * $I_{max}$} is then added to the image.
151 Input Parameters:
152 outfile Output image file name
153 rm Rotation Measure (rad/m/m). Default is auto no-ambiguity determine.
154 pa0 Position angle (degrees) at zero wavelength
155 sigma Fractional noise level
156 nx Shape of image in x direction
157 ny Shape of image in y direction
158 nf Shape of image in frequency direction
159 f0 Reference frequency (Hz)
160 bw Bandwidth (Hz)
162 Example:
165 #
166 print 't----t imagepoltestimage Ex 1 t----'
167 po.imagepoltestimage(outfile='imagepoltestimage', rm=200)
168 po.rotationmeasure(rm='rm.out',rmmax=250)
169 ia.open('rm.out')
170 ia.statistics()
171 #viewer()
172 #
175 --------------------------------------------------------------------------------
177 """
178 return _imagepol.imagepol_imagepoltestimage(self, *args, **kwargs)
181 def complexlinpol(self, *args, **kwargs):
182 """
183 complexlinpol(self, _outfile) -> bool
187 Summary:
188 Complex linear polarization
190 Description:
194 This function produces
195 the complex linear polarization; $Q+iU$ and writes
196 it to a disk image file.
198 The Image tool cannot yet handle Complex
199 images. You must therefore write the Complex image to disk. The
200 Viewer can display Complex images. Also the
201 Table tool can access Complex images.
203 Input Parameters:
204 outfile Output image file name
206 Example:
209 #
210 print 't----t complexlinpol Ex 1 t----'
211 po.open('stokes.image')
212 po.complexlinpol('cplx')
213 tb.open('cplx')
214 #tb.browse()
215 #
218 --------------------------------------------------------------------------------
220 """
221 return _imagepol.imagepol_complexlinpol(self, *args, **kwargs)
224 def complexfraclinpol(self, *args, **kwargs):
225 """
226 complexfraclinpol(self, _outfile) -> bool
230 Summary:
231 Complex fractional linear polarization
233 Description:
237 This function produces
238 the complex fractional linear polarization; $(Q+iU)/I$ and writes
239 it to a disk image file.
241 The Image tool cannot yet handle Complex
242 images. You must therefore write the Complex image to disk. The
243 Viewer can display Complex images. Also the
244 Table tool can access Complex images.
246 Input Parameters:
247 outfile Output image file name
249 Example:
252 #
253 print 't----t complexfraclinpol Ex 1 t----'
254 po.open('stokes.image')
255 po.complexfraclinpol('cplx2')
256 tb.open('cplx2')
257 #tb.browse()
258 #
261 --------------------------------------------------------------------------------
263 """
264 return _imagepol.imagepol_complexfraclinpol(self, *args, **kwargs)
267 def depolratio(self, *args, **kwargs):
268 """
269 depolratio(self, _infile, _debias, _clip, _sigma, _outfile) -> casac::image *
273 Summary:
274 Linear depolarization ratio
276 Description:
280 This function returns the linear
281 depolarization ratio computed from two frequencies; this is the ratio of
282 the fractional linear polarization at the two frequencies. Generally
283 this is done when you have generated two images, each at a different frequency
284 (continuum work). Thus if the fractional linear polarization images are
285 $m_{nu 1}$ and $m_{nu 2}$ then the depolarization ratio is
286 $m_{nu 1}/ m_{nu 2}$.
288 This function operates with two images; the first (at frequency $nu 1$)
289 is the one attached to your Imagepol tool. The second (at
290 frequency $nu 2$) is supplied via the argument {stfaf infile}, which
291 is a String holding the name of the
292 imagefile.
294 In generating the depolarization ratio, you may optionally debias the
295 linearly polarized intensity. This requires the standard deviation of
296 the thermal noise. You can either supply it if you know it, or it will
297 be worked out for you with outliers from the mean clipped at the
298 specified level.
300 You can get the depolarization ratio error image with function
301 sigmadepolratio.
303 Input Parameters:
304 infile Other image
305 debias Debias the linearly polarized intensity ?
306 clip Clip level for auto-sigma determination
307 sigma Standard deviation of thermal noise. Default is auto determined.
308 outfile Output image file name. Default is unset.
310 Example:
313 #
314 #print 't----t depolratio Ex 1 t----'
315 #po.open('stokes.4800')
316 #dpr = po.depolratio(infile='stokes.8300') # m_4800 / m_8300
317 #edpr = po.sigmadepolratio(infile='stokes.8300');
318 #dpr.done()
319 #edpr.done()
320 #
323 --------------------------------------------------------------------------------
325 """
326 return _imagepol.imagepol_depolratio(self, *args, **kwargs)
329 def close(self):
330 """
331 close(self) -> bool
335 Summary:
336 Close the image tool
338 Description:
342 This function closes the imagepol tool. This means that it detaches
343 the tool from its imagefile (flushing all the changes first). The
344 imagepol tool is ``null'' after this change (it is not destroyed) and
345 calling any toolfunction other than open will result in an
346 error.
348 Example:
351 #
352 print 't----t close Ex 1 t----'
353 # First create image and attach it to imagepol tool
354 po.imagepoltestimage('myimagepol')
355 po.close() # Detaches image from Imagepol tool
356 print '!!!EXPECT ERROR HERE!!!'
357 po.summary() # No image so this results in an error.
358 po.open('myimagepol') # Image is reattached
359 po.summary() # No error
360 po.close()
361 #
364 --------------------------------------------------------------------------------
366 """
367 return _imagepol.imagepol_close(self)
370 def done(self):
371 """
372 done(self) -> bool
376 Summary:
377 Close this Imagepol tool
379 Description:
385 This function is the same as close().
387 Example:
390 #
391 print 't----t done Ex 1 t----'
392 po.open('myimagepol')
393 po.done() # Detaches image from Imagepol tool
394 print '!!!EXPECT ERROR HERE!!!'
395 po.summary() # No image so this results in an error.
396 po.open('myimagepol') # Image is reattached
397 po.summary() # No error
398 po.done()
399 #
402 --------------------------------------------------------------------------------
404 """
405 return _imagepol.imagepol_done(self)
408 def fourierrotationmeasure(self, *args, **kwargs):
409 """
410 fourierrotationmeasure(self, _complex, _amp, _pa, _real, _imag, _zerolag0) -> bool
414 Summary:
415 Find Rotation Measure (Fourier approach)
417 Description:
421 This function will only work if
422 you attach the Imagepol tool (using open) to an image containing
423 Stokes Q and U, and a regular frequency axis. It Fourier transforms
424 the complex linear polarization (Q+iU) over the spectral axis to the
425 rotation measure axis. Thus, if your input image contained
426 RA/DEC/Stokes/Frequency, the output image would be
427 RA/DEC/RotationMeasure. The Rotation Measure axis has as many pixels
428 as the spectral axis.
430 This method enables you to see the polarization as a function of
431 Rotation Meausure. Its main use is when searching for large RMs. See
432 Killeen, Fluke, Zhao and Ekers (1999, preprint) for a description of
433 this method (or http://www.atnf.csiro.au/verb+~+nkilleen/rm.ps) and its
434 advantages over the traditional method
435 (rotationmeasure) of
436 extracting the Rotation Measure.
438 Although you can write out the complex polarization image with the
439 argument {stfaf complex}, you can't do much with it because Image
440 tools cannot handle complex images. Hence you can
441 also write out the complex linear polarization image in any or all of
442 the other forms.
444 The argument {stfaf zerolag0} allows you to force the zero lag (or
445 central bin) of the Rotation Measure spectrum to zero (effectively by
446 subtracting the mean of Q and U from the Q and U images). This may
447 avoid Gibbs phenomena from any strong low Rotation Measure signal which
448 would normally fall into the central bin.
450 Input Parameters:
451 complex Output complex linear polarization image file name. Default is unset.
452 amp Output linear polarization amplitude image file name Default is unset.
453 pa Output linear polarization position angle (degrees) image file name Default is unset.
454 real Output linear polarization real image file name Default is unset.
455 imag Output linear polarization imaginary angle image file name Default is unset.
456 zerolag0 Force zero lag to 0 ?
458 Example:
461 #
462 print 't----t fourierrotationmeasure Ex 1 t----'
463 po.imagepoltestimage(outfile='iquv.im', rm=[5.0e5,1e6], nx=8, ny=8, nf=512,
464 f0=1.4e9, bw=8e6)
465 po.fourierrotationmeasure(amp='amp')
466 ia.open('amp')
467 ia.statistics()
468 #viewer() # And reorder to put RM along X-axis
469 #
472 --------------------------------------------------------------------------------
474 """
475 return _imagepol.imagepol_fourierrotationmeasure(self, *args, **kwargs)
478 def fraclinpol(self, *args, **kwargs):
479 """
480 fraclinpol(self, _debias, _clip, _sigma, _outfile) -> casac::image *
484 Summary:
485 Fractional linear polarization
487 Description:
489 This function
490 returns the fractional linear polarization; $sqrt{(Q^2+U^2)}/I$.
492 You may optionally debias the polarized intensity. This requires the
493 standard deviation of the thermal noise. You can either supply it if
494 you know it, or it will be worked out for you with outliers from the
495 mean clipped at the specified level.
497 Input Parameters:
498 debias Debias the linearly polarized intensity ?
499 clip Clip level for auto-sigma determination
500 sigma Standard deviation of thermal noise. Default is auto determined.
501 outfile Output image file name Default is unset.
503 Example:
506 #
507 print 't----t fraclinpol Ex 1 t----'
508 po.open('stokes.image')
509 flp = po.fraclinpol()
510 flp.summary()
511 flp.done()
512 #
515 --------------------------------------------------------------------------------
517 """
518 return _imagepol.imagepol_fraclinpol(self, *args, **kwargs)
521 def fractotpol(self, *args, **kwargs):
522 """
523 fractotpol(self, _debias, _clip, _sigma, _outfile) -> casac::image *
527 Summary:
528 Fractional total polarization
530 Description:
532 This function
533 returns the fractional linear polarization; $sqrt{(Q^2+U^2+V^2)}/I$.
535 You may optionally debias the polarized intensity. This requires the
536 standard deviation of the thermal noise. You can either supply it if
537 you know it, or it will be worked out for you with outliers from the
538 mean clipped at the specified level.
540 If your image contains only Q and U, or only V, then just
541 those components contribute to the total polarized intensity.
543 Input Parameters:
544 debias Debias the total polarized intensity ?
545 clip Clip level for auto-sigma determination
546 sigma Standard deviation of thermal noise. Default is auto determined.
547 outfile Output image file name. Default is unset.
549 Example:
552 #
553 print 't----t fractotpol Ex 1 t----'
554 po.open('stokes.image')
555 ftp = po.fractotpol()
556 ftp.statistics()
557 ftp.done()
558 #
561 --------------------------------------------------------------------------------
563 """
564 return _imagepol.imagepol_fractotpol(self, *args, **kwargs)
567 def linpolint(self, *args, **kwargs):
568 """
569 linpolint(self, _debias, _clip, _sigma, _outfile, _region, _mask, _stretch) -> casac::image *
573 Summary:
574 Linearly polarized intensity
576 Description:
579 This application returns the linearly polarized intensity; $sqrt{(Q^2+U^2)}$.
581 The linearly polarized intensity may optionally be debiased (if debias=True).
582 This requires an estimate of the thermal noise level (sigma). The resulting
583 image will be computed using
585 $sqrt{(Q^2 + U^2 - sigma^2)}$
587 If the specified value of sigma is positive, that is the value that will
588 be used for debiasing. If it is not, the value used for sigma is computed
589 using the following algorithm:
591 1. First, a stokes plane(s) is chosen on which the sigma computation is performed.
592 If the V plane exists, that is used to compute sigma. If not, then the value of
593 sigma is computed to be the average of the sigma values of the Q and U planes.
595 2. For the relevant plane(s), the sigma value is computed for unmasked pixel values
596 which lie within +/- (clip * stddev) values of the mean for that plane, where the mean
597 and stddev (the standard deviation) are computed by using all unmasked pixel values
598 in the relevant plane. In this way, outliers (eg pixels due to possible
599 astronomical signals) are excluded in the computation of sigma.
601 In the output image, pixels for which the expression inside the square root is
602 negative are masked, and their values are set to zero.
604 If a region and/or mask is specified, debias=True and sigma is not positive so
605 that the value of sigma is determined using the algorithm above, the region and mask
606 are applied first to the plane(s) from which the value of sigma is determined and
607 then sigma is computed.
609 Input Parameters:
610 debias Debias the linearly polarized intensity ?
611 clip Clip level for auto-sigma determination
612 sigma Standard deviation of thermal noise. Default is auto determined.
613 outfile Output image file name. Default is unset.
614 region Region selection. Default is to use the full image.
615 mask Mask to use. Default setting is none.
616 stretch Stretch the mask if necessary and possible? Default value is false.
618 Example:
621 #
622 print 't----t linpolint Ex 1 t----'
623 po.open('stokes.image')
624 lpi = po.linpolint()
625 lpi.statistics()
626 lpi.done()
627 #
630 --------------------------------------------------------------------------------
632 """
633 return _imagepol.imagepol_linpolint(self, *args, **kwargs)
636 def linpolposang(self, *args, **kwargs):
637 """
638 linpolposang(self, _outfile, _region, _mask, _stretch) -> casac::image *
642 Summary:
643 Linearly polarized position angle
645 Description:
649 This function returns the linearly polarized position angle image 0.5*arctan(U/Q) in degrees.
650 The output image will not have a restoring beam, even if the input image does.
652 Input Parameters:
653 outfile Output image file name. Default is unset.
654 region Region selection. Default is to use the full image.
655 mask Mask to use. Default setting is none.
656 stretch Stretch the mask if necessary and possible? Default value is false.
658 Example:
661 #
662 print 't----t linpolposang Ex 1 t----'
663 po.open('stokes.image')
664 lppa = po.linpolposang()
665 lppa.statistics()
666 lppa.done()
667 #
670 --------------------------------------------------------------------------------
672 """
673 return _imagepol.imagepol_linpolposang(self, *args, **kwargs)
676 def makecomplex(self, *args, **kwargs):
677 """
678 makecomplex(self, _complex, _real, _imag, _amp, _phase) -> bool
682 Summary:
683 Make a Complex image
685 Description:
689 This function generates a Complex imagefile from either
690 a real and imaginary, or an amplitude and phase pair of images.
691 If you give a linear position angle image for the phase,
692 it will be multipled by two before the real and imaginary
693 parts are formed.
695 Input Parameters:
696 complex Output complex image file name. Must be specified.
697 real Input real image file name. Default is unset.
698 imag Input imaginary image file name. Default is unset.
699 amp Input amplitude image file name. Default is unset.
700 phase Input phase image file name. Default is unset.
702 Example:
705 #
706 print 't----t makecomplex Ex 1 t----'
707 po.open('stokes.image')
708 po.complexlinpol('qu.cplx1')
709 q = po.stokesq()
710 u = po.stokesu()
711 q2 = q.subimage('q',overwrite=true)
712 u2 = u.subimage('u',overwrite=true)
713 po.makecomplex('qu.cplx2', real='q', imag='u')
714 po.close()
715 #
718 In this example we make two complex linear polarization
719 images which should be identical.
721 --------------------------------------------------------------------------------
723 """
724 return _imagepol.imagepol_makecomplex(self, *args, **kwargs)
727 def open(self, *args, **kwargs):
728 """
729 open(self, _image) -> bool
733 Summary:
734 Open a new image with this imagepol tool
736 Description:
740 Before polarimetric analysis can commence, an imagefile must be
741 attached to the imagepol tool using the open function. Also, use this
742 function when you are finished analyzing the current imagefile and
743 want to attach to another one. This function detaches the imagetool
744 from the current imagefile, if one exists, and reattaches it (opens)
745 to the new imagefile.
747 The input image file may be in native casa, fits, or Miriad
748 format. Look htmlref{here}{IMAGES:FOREIGNIMAGES} for more
749 information on foreign images.
751 The input image must have a Stokes axis. The exact collection of
752 Stokes that the image has, determines what the Imagepol tool can
753 compute. Stokes I, Q, U, and V refer to total intensity, two
754 components of linear polarization, and circular polatization,
755 respectively. Therefore, if you ask for linear polarization and the
756 image only has Stokes I and V, you will get an error.
758 The input image may contain data at many frequencies. For example, the
759 image may be a 4D image with axes RA, DEC, Stokes and Frequency (order
760 not important) where the Frequency axis is regularly sampled. However,
761 the image may also contain many frequencies at irregular
762 intervals. Such an image may be created with the Image tool function
763 imageconcat. It enables you to concatenate images along an axis, and
764 it allows irregular coordinate values along that axis.
766 Input Parameters:
767 image image file name or image record (generated by ia.torecord())
769 Example:
772 #
773 print 't----t open Ex 1 t----'
774 po.open('stokes.image')
775 po.close()
776 #
779 The {stff open} function first closes the old imagefile if one exists.
781 --------------------------------------------------------------------------------
783 """
784 return _imagepol.imagepol_open(self, *args, **kwargs)
787 def pol(self, *args, **kwargs):
788 """
789 pol(self, _which, _debias, _clip, _sigma, _outfile) -> casac::image *
793 Summary:
794 Polarized quantities
796 Description:
800 This function just packages the other specific polarization
801 functions into one where you specify an operation with the
802 argument {stfaf which} (can be useful for scripts).
803 This argument can take the values:
805 begin{itemize}
806 item 'lpi' - linearly polarized intensity (function
807 linpolint)
809 item 'tpi' - total polarized intensity (function
810 totpolint)
812 item 'lppa' linearly polarized position angle (function
813 linpolposang)
815 item 'flp' - fractional linear polarization (function
816 fraclinpol)
818 item 'ftp' - fractional total polarized intensity (function
819 fractotpol)
821 end{itemize}
823 Input Parameters:
824 which Specify operation. One of 'lpi', 'tpi', 'lppa', 'flp', 'ftp' (case insensitive)
825 debias Debias the polarized intensity ?
826 clip Clip level for auto-sigma determination
827 sigma Standard deviation of thermal noise. Default is auto determined.
828 outfile Output image file name. Default is unset.
830 Example:
833 #
834 print 't----t pol Ex 1 t----'
835 po.open('stokes.image')
836 lpi = po.pol('lpi')
837 lpi.statistics()
838 lpi.done()
839 #
842 --------------------------------------------------------------------------------
844 """
845 return _imagepol.imagepol_pol(self, *args, **kwargs)
848 def rotationmeasure(self, *args, **kwargs):
849 """
850 rotationmeasure(self, _rm, _rmerr, _pa0, _pa0err, _nturns, _chisq, _sigma, _rmfg, _rmmax, _maxpaerr, _plotter, _nx, _ny) -> bool
854 Summary:
855 Find Rotation Measure (traditional approach)
857 Description:
861 This function generates the rotation
862 measure image from a collection of different frequencies. It will only
863 work if the Imagepol tool is attached to an image containing
864 Stokes $Q$ and $U$, and a frequency axis (regular or irregular) with at
865 least 2 pixels. It will work out the position angle images for you.
867 See also the fourierrotationmeasure
868 function for a new Fourier-based approach.
870 Rotation Measure algorithms that work robustly are not common. The main
871 problem is in trying to account for the $n- pi$ ambiguity (see Leahy et
872 al, Astronomy & Astrophysics, 156, 234 or Killeen et al;
873 http://www.atnf.csiro.au/verb+~+nkilleen/rm.ps).
875 The algorithm that this function uses is that of Leahy et al. (see Appendix A.1). But as in all
876 these algorithms, the basic process is that for each spatial pixel, a
877 vector of position angles (i.e. at the different frequencies) is fit to
878 determine the rotation measure and the position angle at zero wavelength
879 (and their errors). An image containing
880 the number of $n- pi$ turns that were added to the data
881 at each spatial pixel and for which the best fit was found can be written.
882 The reduced chi-squared image for the fits can also be written.
884 Note that no assessment of curvature (i.e. deviation
885 from the simple linear position angle - $lambda^2$ functional form)
886 is made.
888 Any combination of output images can be written.
890 The argument {stfaf sigma} gives the thermal noise in Stokes Q and U.
891 By default it is determined automatically using the image data. But if it proves
892 to be inaccurate (maybe not many signal-free pixels), it may be specified.
893 This is used for calculating the error in the
894 position angles (propagation of Gaussian errors).
896 The argument {stfaf maxpaerr} specifies the maximum allowable error in
897 the position angle that is acceptable. The default is an infinite
898 value. From the standard propagation of errors, the error in the
899 linearly polarized position angle is determined from the Stokes $Q$ and
900 $U$ images (at each spatial pixel for each frequency). At each spatial
901 pixel we do a fit to the position angle vector (i.e. at the different
902 frequencies) to determine the rotation measure. If the position angle
903 error for any pixel in the vector exceeds the specified value, it is
904 dropped from the fit. The process generates an error for the
905 fit and this is used to compute the errors in the output
906 images.
908 Note that {stfaf maxpaerr} is {it not} used to specify that any pixel
909 for which the output position angle error exceeds this value
910 should be masked out.
912 The argument {stfaf rmfg} is used to specify a foreground RM value. For
913 example, you may know the mean RM in some direction out of the Galaxy,
914 then including this can aid the algorithm by reducing ambiguity.
916 The argument {stfaf rmmax} specifies the maximum absolute RM that
917 should be solved for. This quite an important parameter. If you leave
918 it at the default, zero, no ambiguity handling will be
919 used. So some apriori information should be supplied; this
920 is the basic problem with rotation measure algorithms.
922 Input Parameters:
923 rm Output Rotation Measure image file name. Default is unset.
924 rmerr Output Rotation Measure error image file name. Default is unset.
925 pa0 Output position angle (degrees) at zero wavelength image file name. Default is unset.
926 pa0err Output position angle (degrees) at zero wavelength error image file name. Default is unset.
927 nturns Output number of turns image file name. Default is unset.
928 chisq Output reduced chi squared image file name. Default is unset.
929 sigma Estimate of the thermal noise. Default is auto estimate.
930 rmfg Foreground Rotation Measure (rad/m/m) to subtract.
931 rmmax Maximum rotation measure (rad/m/m) to solve for. IMPORTANT TO SPECIFY.
932 maxpaerr Maximum input position angle error (degrees) to allow
933 plotter Name of plotter. Default is none.
934 nx Number of plots in x direction
935 ny Number of plots in y direction
937 Example:
940 #
941 print 't----t rotationmeasure Ex 1 t----'
942 #im = ia.imageconcat(outfile='stokes.image',
943 # infiles='im.f1 im.f2 im.f3 im.f4 im.f5', axis=4)
944 po.open('stokes.image')
945 ok = po.rotationmeasure(rm='rm', rmerr='rmerr', rmmax=800, maxpaerr=10)
946 #
950 Say we have 5 images, each with axes RA, DEC, Stokes, and Frequency in
951 that order. We use the Image tool to concatenate these images
952 along the frequency axis - you have ordered them in increasing or
953 decreasing frequency order. We then compute the Rotation Measure
954 and Rotation Measure error images with the traditional method and
955 write them out to disk.
957 --------------------------------------------------------------------------------
959 """
960 return _imagepol.imagepol_rotationmeasure(self, *args, **kwargs)
963 def sigma(self, *args, **kwargs):
964 """
965 sigma(self, _clip) -> double
969 Summary:
970 Find best guess at thermal noise
972 Description:
976 This function returns the standard deviation from V, Q&U or I in that
977 order of precedence. It is attempting to give you the best estimate of
978 the thermal noise it can from the data. Outliers from the mean are
979 clipped at the specified level.
981 Input Parameters:
982 clip Clip level for auto-sigma determination
984 Example:
987 #
988 print 't----t sigma Ex 1 t----'
989 po.open('stokes.image')
990 sigma = po.sigma()
991 print 'sigma=', sigma
992 #
995 --------------------------------------------------------------------------------
997 """
998 return _imagepol.imagepol_sigma(self, *args, **kwargs)
1001 def sigmadepolratio(self, *args, **kwargs):
1002 """
1003 sigmadepolratio(self, _infile, _debias, _clip, _sigma, _outfile) -> casac::image *
1007 Summary:
1008 Error in linear depolarization ratio
1010 Description:
1014 This function returns the error
1015 in the linear depolarization ratio computed from two frequencies; this
1016 is the ratio of the fractional linear polarization at the two
1017 frequencies. Generally this is done when you have generated two
1018 images, each at a different frequency (continuum work). Thus if the
1019 fractional linear polarzation images are $m1$ and $m2$ then the
1020 depolarization ratio is $m1/m2$.
1022 This function operates with two images; the first is attached
1023 to the Imagepol tool. The second is supplied via the
1024 argument {stfaf infile}, which is a String
1025 holding the name of the imagefile.
1027 In generating the depolarization ratio, and hence its error, you may
1028 optionally debias the linearly polarized intensity. This requires the
1029 standard deviation of the thermal noise. You can either supply it if
1030 you know it, or it will be worked out for you with outliers from the
1031 mean clipped at the specified level.
1033 You can get the depolarization ratio image with function
1034 depolratio.
1036 Input Parameters:
1037 infile Other image. Required input.
1038 debias Debias the linearly polarized intensity ?
1039 clip Clip level for auto-sigma determination
1040 sigma Standard deviation of thermal noise. Default is auto determined.
1041 outfile Output image file name. Default is unset.
1043 Example:
1046 #
1047 #print 't----t sigmadepolratio Ex 1 t----'
1048 #po.open('stokes.4800')
1049 #dpr = po.depolratio('stokes.8300')
1050 #edpr = po.sigmadepolratio('stokes.8300');
1051 #dpr.done()
1052 #edpr.done()
1053 #
1056 --------------------------------------------------------------------------------
1058 """
1059 return _imagepol.imagepol_sigmadepolratio(self, *args, **kwargs)
1062 def sigmafraclinpol(self, *args, **kwargs):
1063 """
1064 sigmafraclinpol(self, _clip, _sigma, _outfile) -> casac::image *
1068 Summary:
1069 Error in fractional linear polarization
1071 Description:
1075 This function returns the
1076 error (standard deviation) of the fractional linear polarization.
1077 This result comes from standard propagation of errors. The result is
1078 an on-the-fly Image tool as the error is signal-to-noise ratio
1079 dependent.
1081 This function requires the standard deviation of the thermal noise. You
1082 can either supply it if you know it, or it will be worked out for you
1083 with outliers from the mean clipped at the specified level.
1085 Input Parameters:
1086 clip Clip level for auto-sigma determination
1087 sigma Standard deviation of thermal noise. Default is auto determined.
1088 outfile Output image file name. Default is unset.
1090 Example:
1093 #
1094 print 't----t sigmafraclinpol Ex 1 t----'
1095 po.open('stokes.image')
1096 sigflp = po.sigmafraclinpol()
1097 sigflp.statistics()
1098 sigflp.done() # free up resources
1099 #
1102 --------------------------------------------------------------------------------
1104 """
1105 return _imagepol.imagepol_sigmafraclinpol(self, *args, **kwargs)
1108 def sigmafractotpol(self, *args, **kwargs):
1109 """
1110 sigmafractotpol(self, _clip, _sigma, _outfile) -> casac::image *
1114 Summary:
1115 Error in fractional total polarization
1117 Description:
1121 This function returns the
1122 error (standard deviation) of the fractional total polarization. This
1123 result comes from standard propagation of errors. The result is an
1124 on-the-fly Image tool as the error is signal-to-noise ratio dependent.
1126 This function requires the standard deviation of the thermal noise. You
1127 can either supply it if you know it, or it will be worked out for you
1128 with outliers from the mean clipped at the specified level.
1130 Input Parameters:
1131 clip Clip level for auto-sigma determination
1132 sigma Standard deviation of thermal noise. Default is auto determined.
1133 outfile Output image file name. Default is unset.
1135 Example:
1138 #
1139 print 't----t sigmafractotpol Ex 1 t----'
1140 po.open('stokes.image')
1141 sigftp = po.sigmafractotpol()
1142 sigftp.statistics()
1143 sigftp.done()
1144 #
1147 --------------------------------------------------------------------------------
1149 """
1150 return _imagepol.imagepol_sigmafractotpol(self, *args, **kwargs)
1153 def sigmalinpolint(self, *args, **kwargs):
1154 """
1155 sigmalinpolint(self, _clip, _sigma, _outfile) -> double
1159 Summary:
1160 Error in linearly polarized intensity
1162 Description:
1166 This function returns the error (standard
1167 deviation) of the linearly polarized intensity; $sqrt{(Q^2+U^2)}$.
1168 This result comes from standard propagation of statistical errors.
1169 The result is a float as the error is not signal-to-noise
1170 ratio dependent
1172 This function requires the standard deviation of the thermal noise. You
1173 can either supply it if you know it, or it will be worked out for you
1174 with outliers from the mean clipped at the specified level.
1176 Input Parameters:
1177 clip Clip level for auto-sigma determination
1178 sigma Standard deviation of thermal noise. Default is auto determined.
1179 outfile Output image file name. Default is unset.
1181 Example:
1184 #
1185 print 't----t sigmalinpolint Ex 1 t----'
1186 po.open('stokes.image')
1187 siglpi = po.sigmalinpolint()
1188 print 'siglpi=', siglpi
1189 #
1192 --------------------------------------------------------------------------------
1194 """
1195 return _imagepol.imagepol_sigmalinpolint(self, *args, **kwargs)
1198 def sigmalinpolposang(self, *args, **kwargs):
1199 """
1200 sigmalinpolposang(self, _clip, _sigma, _outfile) -> casac::image *
1204 Summary:
1205 Error in linearly polarized position angle
1207 Description:
1211 This function returns the
1212 error (standard deviation) of the linearly polarized position angle
1213 ($0.5 tan^{-1}(U/Q)$$sqrt{(Q^2+U^2)}$) in degrees. This result
1214 comes from standard propagation of errors. The result is an
1215 on-the-fly Image tool as the error is signal-to-noise ratio dependent.
1217 This function requires the standard deviation of the thermal noise. You
1218 can either supply it if you know it, or it will be worked out for you
1219 with outliers from the mean clipped at the specified level.
1221 Input Parameters:
1222 clip Clip level for auto-sigma determination
1223 sigma Standard deviation of thermal noise. Default is auto determined.
1224 outfile Output image file name. Default is unset.
1226 Example:
1229 #
1230 print 't----t sigmalinpolposang Ex 1 t----'
1231 po.open('stokes.image')
1232 siglppa = po.sigmalinpolposang()
1233 siglppa.statistics()
1234 siglppa.done()
1235 #
1238 --------------------------------------------------------------------------------
1240 """
1241 return _imagepol.imagepol_sigmalinpolposang(self, *args, **kwargs)
1244 def sigmastokes(self, *args, **kwargs):
1245 """
1246 sigmastokes(self, _which, _clip) -> double
1250 Summary:
1251 Find standard deviation of specified Stokes data
1253 Description:
1257 This function returns the standard
1258 deviation of the noise for the specified Stokes. Outliers from the mean
1259 are clipped at the specified level.
1261 Input Parameters:
1262 which Must specify Stokes parameter. One of 'I', 'Q', 'U', 'V' (case insensitive)
1263 clip Clip level for auto-sigma determination
1265 Example:
1268 #
1269 print 't----t sigmastokes Ex 1 t----'
1270 po.open('stokes.image')
1271 sigq = po.sigmastokes('q', 10.0)
1272 print 'sigq=', sigq
1273 #
1276 --------------------------------------------------------------------------------
1278 """
1279 return _imagepol.imagepol_sigmastokes(self, *args, **kwargs)
1282 def sigmastokesi(self, *args, **kwargs):
1283 """
1284 sigmastokesi(self, _clip) -> double
1288 Summary:
1289 Find standard deviation of Stokes I data
1291 Description:
1295 This function returns the standard deviation of the noise for the
1296 Stokes I data. Outliers from the mean are clipped at the specified
1297 level.
1299 Input Parameters:
1300 clip Clip level for auto-sigma determination
1302 Example:
1305 #
1306 print 't----t sigmastokesi Ex 1 t----'
1307 po.open('stokes.image')
1308 sigi = po.sigmastokesi(10.0)
1309 print 'sigi=', sigi
1310 #
1313 --------------------------------------------------------------------------------
1315 """
1316 return _imagepol.imagepol_sigmastokesi(self, *args, **kwargs)
1319 def sigmastokesq(self, *args, **kwargs):
1320 """
1321 sigmastokesq(self, _clip) -> double
1325 Summary:
1326 Find standard deviation of Stokes Q data
1328 Description:
1332 This function returns the standard deviation of the noise for the
1333 Stokes Q data. Outliers from the mean are clipped at the specified
1334 level.
1336 Input Parameters:
1337 clip Clip level for auto-sigma determination
1339 Example:
1342 #
1343 print 't----t sigmastokesq Ex 1 t----'
1344 po.open('stokes.image')
1345 sigq = po.sigmastokesq(10.0)
1346 print 'sigq=', sigq
1347 #
1350 --------------------------------------------------------------------------------
1352 """
1353 return _imagepol.imagepol_sigmastokesq(self, *args, **kwargs)
1356 def sigmastokesu(self, *args, **kwargs):
1357 """
1358 sigmastokesu(self, _clip) -> double
1362 Summary:
1363 Find standard deviation of Stokes U data
1365 Description:
1369 This function returns the standard
1370 deviation of the noise for the Stokes U data. Outliers from the mean
1371 are clipped at the specified level.
1373 Input Parameters:
1374 clip Clip level for auto-sigma determination
1376 Example:
1379 #
1380 print 't----t sigmastokesu Ex 1 t----'
1381 po.open('stokes.image')
1382 sigu = po.sigmastokesu(10.0)
1383 print 'sigu=', sigu
1384 #
1387 --------------------------------------------------------------------------------
1389 """
1390 return _imagepol.imagepol_sigmastokesu(self, *args, **kwargs)
1393 def sigmastokesv(self, *args, **kwargs):
1394 """
1395 sigmastokesv(self, _clip) -> double
1399 Summary:
1400 Find standard deviation of Stokes V data
1402 Description:
1406 This function returns the standard
1407 deviation of the noise for the Stokes V data. Outliers from the mean
1408 are clipped at the specified level.
1410 Input Parameters:
1411 clip Clip level for auto-sigma determination
1413 Example:
1416 #
1417 print 't----t sigmastokesv Ex 1 t----'
1418 po.open('stokes.image')
1419 sigv = po.sigmastokesv(10.0)
1420 print 'sigv=', sigv
1421 #
1424 --------------------------------------------------------------------------------
1426 """
1427 return _imagepol.imagepol_sigmastokesv(self, *args, **kwargs)
1430 def sigmatotpolint(self, *args, **kwargs):
1431 """
1432 sigmatotpolint(self, _clip, _sigma) -> double
1436 Summary:
1437 Error in total polarized intensity
1439 Description:
1443 This function returns the error (standard
1444 deviation) of the total polarized intensity; $sqrt{(Q^2+U^2+V^2)}$.
1445 This result comes from standard propagation of statistical errors.
1446 The result is a float as the error is not signal-to-noise
1447 ratio dependent
1449 This function requires the standard deviation of the thermal noise. You
1450 can either supply it if you know it, or it will be worked out for you
1451 with outliers from the mean clipped at the specified level.
1453 Input Parameters:
1454 clip Clip level for auto-sigma determination
1455 sigma Standard deviation of thermal noise. Default is auto determined.
1457 Example:
1460 #
1461 print 't----t sigmastotpolint Ex 1 t----'
1462 po.open('stokes.image')
1463 sigtpi = po.sigmatotpolint()
1464 print 'sigtpi=', sigtpi
1465 #
1468 --------------------------------------------------------------------------------
1470 """
1471 return _imagepol.imagepol_sigmatotpolint(self, *args, **kwargs)
1474 def stokes(self, *args, **kwargs):
1475 """
1476 stokes(self, _which, _outfile) -> casac::image *
1480 Summary:
1481 Stokes
1483 Description:
1487 This function returns an on-the-fly image tool containing the
1488 specified Stokes only. This interface can be useful for scripts.
1490 Input Parameters:
1491 which Must specify Stokes. One of 'I', 'Q', 'U', 'V' (case insensitive)
1492 outfile Output image file name. Default is unset.
1494 Example:
1497 #
1498 print 't----t stokes Ex 1 t----'
1499 po.open('stokes.image')
1500 q = po.stokes('q')
1501 q.statistics()
1502 q.done()
1503 #
1506 --------------------------------------------------------------------------------
1508 """
1509 return _imagepol.imagepol_stokes(self, *args, **kwargs)
1512 def stokesi(self, *args, **kwargs):
1513 """
1514 stokesi(self, _outfile) -> casac::image *
1518 Summary:
1519 Stokes I
1521 Description:
1524 This function returns an on-the-fly image tool containing Stokes I only.
1526 Input Parameters:
1527 outfile Output image file name. Default is unset.
1529 Example:
1532 #
1533 print 't----t stokesi Ex 1 t----'
1534 po.open('stokes.image')
1535 i = po.stokesi()
1536 i.statistics()
1537 i.done()
1538 #
1541 --------------------------------------------------------------------------------
1543 """
1544 return _imagepol.imagepol_stokesi(self, *args, **kwargs)
1547 def stokesq(self, *args, **kwargs):
1548 """
1549 stokesq(self, _outfile) -> casac::image *
1553 Summary:
1554 Stokes Q
1556 Description:
1559 This function returns an on-the-fly image tool containing Stokes Q only.
1561 Input Parameters:
1562 outfile Output image file name. Default is unset.
1564 Example:
1567 #
1568 print 't----t stokesq Ex 1 t----'
1569 po.open('stokes.image')
1570 q = po.stokesq()
1571 q.statistics()
1572 q.done()
1573 #
1576 --------------------------------------------------------------------------------
1578 """
1579 return _imagepol.imagepol_stokesq(self, *args, **kwargs)
1582 def stokesu(self, *args, **kwargs):
1583 """
1584 stokesu(self, _outfile) -> casac::image *
1588 Summary:
1589 Stokes U
1591 Description:
1594 This function returns an on-the-fly image tool containing Stokes U only.
1596 Input Parameters:
1597 outfile Output image file name. Default is unset.
1599 Example:
1602 #
1603 print 't----t stokesu Ex 1 t----'
1604 po.open('stokes.image')
1605 u = po.stokesu()
1606 u.statistics()
1607 u.done()
1608 #
1611 --------------------------------------------------------------------------------
1613 """
1614 return _imagepol.imagepol_stokesu(self, *args, **kwargs)
1617 def stokesv(self, *args, **kwargs):
1618 """
1619 stokesv(self, _outfile) -> casac::image *
1623 Summary:
1624 Stokes V
1626 Description:
1629 This function returns an on-the-fly image tool containing Stokes V only.
1631 Input Parameters:
1632 outfile Output image file name. Default is unset.
1634 Example:
1637 #
1638 print 't----t stokesv Ex 1 t----'
1639 po.open('stokes.image')
1640 v = po.stokesv()
1641 v.statistics()
1642 v.done()
1643 #
1646 --------------------------------------------------------------------------------
1648 """
1649 return _imagepol.imagepol_stokesv(self, *args, **kwargs)
1652 def summary(self):
1653 """
1654 summary(self) -> bool
1658 Summary:
1659 Summarise Imagepol tool
1661 Description:
1665 This function just lists a summary of the Imagepol tool to the logger.
1666 Currently it just summarizes the image to which the tool is attached.
1668 Example:
1671 #
1672 print 't----t summary Ex 1 t----'
1673 po.open('stokes.image')
1674 po.summary()
1675 #
1676 #Image name : stokes.image
1677 #Object name :
1678 #Image type : PagedImage
1679 #Image quantity : Intensity
1680 #Pixel mask(s) : None
1681 #Region(s) : None
1682 #
1683 #Direction reference : J2000
1684 #Spectral reference : TOPO
1685 #Velocity type : RADIO
1686 #Rest frequency : 1.4e+09 Hz
1687 #Telescope : UNKNOWN
1688 #Observer : UNKNOWN
1689 #Date observation : UNKNOWN
1690 #
1691 #Axis Coord Type Name Proj Shape Tile Coord value at pixel Coord incr Units
1692 #------------------------------------------------------------------------------------------------
1693 #0 0 Direction Right Ascension SIN 32 32 00:00:00.000 16.00 -6.000000e+01 arcsec
1694 #1 0 Direction Declination SIN 32 32 +00.00.00.000 16.00 6.000000e+01 arcsec
1695 #2 1 Stokes Stokes 4 4 I Q U V
1696 #3 2 Spectral Frequency 32 32 1.4e+09 16.00 4.000000e+06 Hz
1697 # Velocity 0 16.00 -8.565499e+02 km/s
1698 #
1699 #
1702 --------------------------------------------------------------------------------
1704 """
1705 return _imagepol.imagepol_summary(self)
1708 def totpolint(self, *args, **kwargs):
1709 """
1710 totpolint(self, _debias, _clip, _sigma, _outfile, _region, _mask, _stretch) -> casac::image *
1714 Summary:
1715 Total polarized intensity
1717 Description:
1720 This application returns the total polarized intensity;
1722 $sqrt{( Q^2+ U^2+ V^2)}$.
1724 If the image contains only Q and U, or only V, then just
1725 those components contribute to the total polarized intensity.
1727 The polarized intensity may optionally be debiased (if debias=True).
1728 This requires an estimate of the thermal noise level (sigma).
1729 The resulting image will be computed using
1731 $sqrt{(Q^2 + U^2 + V^2 - sigma^2)}$
1733 If the specified value of sigma is positive, that is the value that will
1734 be used for debiasing. If it is not, the value used for sigma is computed
1735 using the following algorithm:
1737 1. First, a stokes plane(s) is chosen on which the sigma computation is performed.
1738 If the V plane exists, that is used to compute sigma. If not, then the value of
1739 sigma is computed to be the average of the sigma values of the Q and U planes.
1741 2. For the relevant plane(s), the sigma value is computed for unmasked pixel values
1742 which lie within +/- (clip * stddev) values of the mean for that plane, where the mean
1743 and stddev (the standard deviation) are computed by using all unmasked pixel values
1744 in the relevant plane. In this way, outliers (eg pixels due to possible
1745 astronomical signals) are excluded in the computation of sigma.
1747 In the output image, pixels for which the expression inside the square root is
1748 negative are masked, and their values are set to zero.
1750 If a region and/or mask is specified, debias=True and sigma is not positive so
1751 that the value of sigma is determined using the algorithm above, the region and mask
1752 are applied first to the plane(s) from which the value of sigma is determined and
1753 then sigma is computed.
1755 Input Parameters:
1756 debias Debias the total polarized intensity ?
1757 clip Clip level for auto-sigma determination
1758 sigma Standard deviation of thermal noised. Default is auto determined.
1759 outfile Output image file name. Default is unset.
1760 region Region selection. Default is to use the full image.
1761 mask Mask to use. Default setting is none.
1762 stretch Stretch the mask if necessary and possible? Default value is false.
1764 Example:
1767 #
1768 print 't----t totpolint Ex 1 t----'
1769 po.open('stokes.image')
1770 tpi = po.totpolint()
1771 tpi.statistics()
1772 tpi.done()
1773 #
1776 --------------------------------------------------------------------------------
1778 """
1779 return _imagepol.imagepol_totpolint(self, *args, **kwargs)
1781 __swig_destroy__ = _imagepol.delete_imagepol
1782 __del__ = lambda self: None
1783imagepol_swigregister = _imagepol.imagepol_swigregister
1784imagepol_swigregister(imagepol)
1786# This file is compatible with both classic and new-style classes.