Merge pull request #132 from AlecThomson/escapes

PEP-257 docstrings

radio_beam/beam.py

@@ -247,7 +247,7 @@ def from_fits_history(cls, hdr):
 
     @classmethod
     def from_casa_image(cls, imagename):
-        '''
+        """
         Instantiate beam from a CASA image.
 
         ** Must be run in a CASA environment! **
@@ -256,7 +256,7 @@ def from_casa_image(cls, imagename):
         ----------
         imagename : str
             Name of CASA image.
-        '''
+        """
 
         try:
             import casac
@@ -284,7 +284,7 @@ def from_casa_image(cls, imagename):
         return cls(major=major, minor=minor, pa=pa)
 
     def attach_to_header(self, header, copy=True):
-        '''
+        """
         Attach the beam information to the provided header.
 
         Parameters
@@ -299,7 +299,7 @@ def attach_to_header(self, header, copy=True):
         copy_header : astropy.io.fits.header.Header
             Copy of the input header with the updated beam info when
             `copy=True`.
-        '''
+        """
 
         if copy:
             header = header.copy()
@@ -457,7 +457,7 @@ def beam_projected_area(self, distance):
         return self.sr*(distance**2)/u.sr
 
     def jtok_equiv(self, freq):
-        '''
+        """
         Return conversion function between Jy/beam to K at the specified
         frequency.
 
@@ -473,7 +473,7 @@ def jtok_equiv(self, freq):
         Returns
         -------
         u.brightness_temperature
-        '''
+        """
 
         if not isinstance(freq, u.quantity.Quantity):
             raise TypeError("freq must be a Quantity object. "
@@ -513,7 +513,7 @@ def beamarea_equiv(self):
         return u.beam_angular_area(self.sr)
 
     def commonbeam_with(self, other_beam):
-        '''
+        """
         Solve for the common beam with a given `~radio_beam.Beam`.
 
         This common beam operation is only valid for a set of 2 beams.
@@ -524,7 +524,7 @@ def commonbeam_with(self, other_beam):
         other_beam : radio_beam.Beam
             The beam to find the common beam with.
 
-        '''
+        """
         from .commonbeam import find_commonbeam_between
 
         return find_commonbeam_between(self, other_beam)
@@ -589,7 +589,7 @@ def as_kernel(self, pixscale, **kwargs):
                                           **kwargs)
 
     def as_tophat_kernel(self, pixscale, **kwargs):
-        '''
+        """
         Returns an elliptical Tophat kernel of the beam. The area has
         been scaled to match the 2D Gaussian area:
 
@@ -609,7 +609,7 @@ def as_tophat_kernel(self, pixscale, **kwargs):
         pixscale : float
             deg -> pixels
         **kwargs : passed to EllipticalTophat2DKernel
-        '''
+        """
 
         # Based on Gaussian to Tophat area conversion
         # A_gaussian = 2 * pi * sigma^2 / (sqrt(8*log(2))^2

radio_beam/commonbeam.py

@@ -17,10 +17,10 @@
 
 
 def commonbeam(beams, method='pts', **method_kwargs):
-    '''
+    """
     Use analytic method if there are only two beams. Otherwise use constrained
     optimization to find the common beam.
-    '''
+    """
 
     if beams.size == 1:
         return beams[0]
@@ -43,7 +43,7 @@ def commonbeam(beams, method='pts', **method_kwargs):
             raise ValueError("method must be 'pts' or 'opt'.")
 
 def common_2beams(beams, check_deconvolution=True):
-    '''
+    """
     Find a common beam from a `Beams` object with 2 beams. This
     function is based on the CASA implementation `ia.commonbeam`. Note that
     the solution is only valid for 2 beams.
@@ -57,7 +57,7 @@ def common_2beams(beams, check_deconvolution=True):
     -------
     common_beam : `~radio_beam.Beam`
         The smallest common beam in the set of beams.
-    '''
+    """
 
     if beams.size != 2:
         raise BeamError("This method is only valid for two beams.")
@@ -69,7 +69,7 @@ def common_2beams(beams, check_deconvolution=True):
 
 
 def find_commonbeam_between(beam1, beam2, check_deconvolution=True):
-    '''
+    """
     Find the common beam between 2 `~radio_beam.Beam` objects.
 
     This function is based on the CASA implementation `ia.commonbeam` that
@@ -89,7 +89,7 @@ def find_commonbeam_between(beam1, beam2, check_deconvolution=True):
     -------
     common_beam : `~radio_beam.Beam`
         The smallest common beam in the set of beams.
-    '''
+    """
 
     # This code is based on the implementation in CASA:
     # https://open-bitbucket.nrao.edu/projects/CASA/repos/casa/browse/code/imageanalysis/ImageAnalysis/CasaImageBeamSet.cc
@@ -229,10 +229,10 @@ def boundingcircle(bmaj, bmin, bpa):
 
 
 def PtoA(bmaj, bmin, bpa):
-    '''
+    """
     Express the ellipse parameters into
     `center-form <https://en.wikipedia.org/wiki/Matrix_representation_of_conic_sections>`_.
-    '''
+    """
     A = np.zeros((2, 2))
     A[0, 0] = np.cos(bpa)**2 / bmaj**2 + np.sin(bpa)**2 / bmin**2
     A[1, 0] = np.cos(bpa) * np.sin(bpa) * (1 / bmaj**2 - 1 / bmin**2)
@@ -273,7 +273,7 @@ def common_manybeams_opt(beams, p0=None, opt_method='Nelder-Mead',
                                   'maxfev': 5000},
                          verbose=False,
                          brute=False, brute_steps=40):
-    '''
+    """
     Optimize the common beam solution by maximizing the determinant of the
     common beam.
 
@@ -302,7 +302,7 @@ def common_manybeams_opt(beams, p0=None, opt_method='Nelder-Mead',
     -------
     com_beam : `~radio_beam.Beam`
         Common beam.
-    '''
+    """
 
     raise NotImplementedError("This method is not fully tested. Remove this "
                               "line for testing purposes.")
@@ -359,9 +359,9 @@ def common_manybeams_opt(beams, p0=None, opt_method='Nelder-Mead',
 
 
 def fits_in_largest(beams, large_beam=None):
-    '''
+    """
     Test if all beams can be deconvolved by the largest beam
-    '''
+    """
 
     if large_beam is None:
         large_beam = beams.largest_beam()
@@ -498,7 +498,7 @@ def getMinVolEllipse(P, tolerance=1e-5, maxiter=1e5):
 
 
 def ellipse_edges(beam, npts=300, epsilon=1e-3):
-    '''
+    """
     Return the edge points of the beam.
 
     Parameters
@@ -516,7 +516,7 @@ def ellipse_edges(beam, npts=300, epsilon=1e-3):
     -------
     pts : `~numpy.ndarray`
         The x, y coordinates of the ellipse edge.
-    '''
+    """
 
     bpa = beam.pa.to(u.rad).value
     major = beam.major.to(u.deg).value * (1. + epsilon)
@@ -539,7 +539,7 @@ def common_manybeams_mve(beams, tolerance=1e-4, nsamps=200,
                          auto_increase_epsilon=True,
                          max_epsilon=1e-3,
                          max_iter=10):
-    '''
+    """
     Calculate a common beam size using the Khachiyan Algorithm to find the
     minimum enclosing ellipse from all beam edges.
 
@@ -574,7 +574,7 @@ def common_manybeams_mve(beams, tolerance=1e-4, nsamps=200,
     -------
     com_beam : `~radio_beam.Beam`
         The common beam for all beams in the set.
-    '''
+    """
 
     if not HAS_SCIPY:
         raise ImportError("common_manybeams_mve requires scipy.optimize.")

radio_beam/multiple_beams.py

@@ -214,7 +214,7 @@ def from_fits_bintable(cls, bintable):
 
     @classmethod
     def from_casa_image(cls, imagename):
-        '''
+        """
         Instantiate beams from a CASA image. Cannot currently handle beams for
         different polarizations.
 
@@ -224,7 +224,7 @@ def from_casa_image(cls, imagename):
         ----------
         imagename : str
             Name of CASA image.
-        '''
+        """
 
         try:
             from casatools import image as iatool
@@ -334,7 +334,7 @@ def extrema_beams(self, includemask=None):
                 self.largest_beam(includemask)]
 
     def common_beam(self, includemask=None, method='pts', **kwargs):
-        '''
+        """
         Return the smallest common beam size. For set of two beams,
         the solution is solved analytically. All larger sets solve for the
         minimum volume ellipse using the
@@ -348,8 +348,8 @@ def common_beam(self, includemask=None, method='pts', **kwargs):
         this issue, a small `epsilon` correction factor is added to the
         ellipse edges to encourage a valid common beam solution.
         Since `epsilon` is added to all sides, this correction will at most
-        increase the common beam size by :math:`2\times(1+\epsilon)`.
-        The default values of `epsilon` is :math:`5\times10^{-4}`, so this
+        increase the common beam size by :math:`2\\times(1+\\epsilon)`.
+        The default values of `epsilon` is :math:`5\\times10^{-4}`, so this
         will have a very small effect on the size of the common beam.
 
         In some cases, `epsilon` must be increased to find a valid common
@@ -370,7 +370,7 @@ def common_beam(self, includemask=None, method='pts', **kwargs):
             Many beam method. Only `pts` is currently available.
         kwargs : Passed to `~radio_beam.commonbeam`.
 
-        '''
+        """
         return commonbeam(self if includemask is None else self[includemask],
                           method=method, **kwargs)
 

radio_beam/tests/data/generate_commonbeam_table.py

@@ -1,11 +1,11 @@
 
-'''
+"""
 
 UNUSED IN CURRENT TESTING SUITE!
 
 Run in a CASA environment to generate the smallest common beam for a range of
 parameters.
-'''
+"""
 
 RUN = False
 

radio_beam/tests/test_beam.py

@@ -352,9 +352,9 @@ def test_beam_equal(major, minor, pa):
                           (10, 8, -120),
                           (10, 8, 240)])
 def test_beam_equal_noncirc(major, minor, pa):
-    '''
+    """
     Beams with PA +/- 180 deg are equal
-    '''
+    """
 
     beam1 = Beam(10 * u.deg, 8 * u.deg, 60 * u.deg)
 
@@ -401,11 +401,11 @@ def test_major_minor_swap():
 
 
 def test_commonbeam_builtin():
-    '''
+    """
     Test the built in common beam for Beam with a 2nd beam.
 
     This test case should come out to a round common beam of 10 arcsec.
-    '''
+    """
 
     beam1 = Beam(10 * u.arcsec, 8 * u.arcsec, 60 * u.deg)
 

radio_beam/tests/test_beams.py

@@ -400,11 +400,11 @@ def test_beams_iter():
 
 
 def test_common_beam_smallcircular():
-    '''
+    """
     Simple solution if the smallest beam is circular with a radius larger:
     Major axis is from the largest beam, minor axis is the radius of the
     smaller, and the PA is from the largest beam.
-    '''
+    """
 
     for pa in [0., 18., 68., 122.]:
         beams = Beams(major=[3, 4] * u.arcsec,
@@ -427,9 +427,9 @@ def test_commonbeam_notlargest():
 
 
 def test_commonbeam_largest():
-    '''
+    """
     commonbeam is the largest in this set.
-    '''
+    """
 
     beams, majors = symm_beams_for_tests()[:2]
 
@@ -628,10 +628,10 @@ def test_commonbeam_methods(beams, target_beam):
 
 
 def test_catch_common_beam_opt():
-    '''
+    """
     The optimization method is close to working, but requires more testing.
     Ensure it cannot be used.
-    '''
+    """
 
     beams = Beams(major=[4] * 4 * u.arcsec, minor=[2] * 4 * u.arcsec,
                   pa=[0, 20, 40, 60] * u.deg)
@@ -651,7 +651,7 @@ def test_major_minor_swap():
 
 
 def test_common_beam_mve_auto_increase_epsilon():
-    '''
+    """
     Here's a case where the default MVE parameters fail.
     By slowly increasing the epsilon* value, we get a common
     beam the can be deconvolved correctly over the set.
@@ -660,7 +660,7 @@ def test_common_beam_mve_auto_increase_epsilon():
     radius: radius * (1 + epsilon). The solution is then marginally
     larger than the true optimal solution, but close enough for
     effectively all use cases.
-    '''
+    """
 
     major = [8.517199, 8.513563, 8.518497, 8.518434, 8.528561, 8.528236,
              8.530046, 8.530528, 8.530696, 8.533117] * u.arcsec

radio_beam/utils.py

@@ -200,7 +200,7 @@ def convolve(beam, other):
 
 
 def transform_ellipse(major, minor, pa, x_scale, y_scale):
-    '''
+    """
     Transform an ellipse by scaling in the x and y axes.
 
     Parameters
@@ -224,7 +224,7 @@ def transform_ellipse(major, minor, pa, x_scale, y_scale):
         Minor axis in the transformed frame.
     trans_pa : `~astropy.units.Quantity`
         PA of the major axis in the transformed frame.
-    '''
+    """
 
     # This code is based on the implementation in CASA:
     # https://open-bitbucket.nrao.edu/projects/CASA/repos/casa/browse/code/imageanalysis/ImageAnalysis/CasaImageBeamSet.cc