From 5df2fe9b7568a7bff5e379a8cb7381e94b366a6a Mon Sep 17 00:00:00 2001 From: "Alec Thomson (S&A, Kensington WA)" Date: Thu, 7 Nov 2024 08:48:45 +0800 Subject: [PATCH] Fix all docstrings --- radio_beam/beam.py | 20 ++++++------ radio_beam/commonbeam.py | 32 +++++++++---------- radio_beam/multiple_beams.py | 4 +-- .../tests/data/generate_commonbeam_table.py | 4 +-- radio_beam/tests/test_beam.py | 8 ++--- radio_beam/tests/test_beams.py | 16 +++++----- radio_beam/utils.py | 4 +-- 7 files changed, 44 insertions(+), 44 deletions(-) diff --git a/radio_beam/beam.py b/radio_beam/beam.py index 9955236..a3b5188 100644 --- a/radio_beam/beam.py +++ b/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 diff --git a/radio_beam/commonbeam.py b/radio_beam/commonbeam.py index 0e2a3bf..c071a60 100644 --- a/radio_beam/commonbeam.py +++ b/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 `_. - ''' + """ 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.") diff --git a/radio_beam/multiple_beams.py b/radio_beam/multiple_beams.py index 1745326..ae1e492 100644 --- a/radio_beam/multiple_beams.py +++ b/radio_beam/multiple_beams.py @@ -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 @@ -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) diff --git a/radio_beam/tests/data/generate_commonbeam_table.py b/radio_beam/tests/data/generate_commonbeam_table.py index 60e73a3..6b327c1 100644 --- a/radio_beam/tests/data/generate_commonbeam_table.py +++ b/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 diff --git a/radio_beam/tests/test_beam.py b/radio_beam/tests/test_beam.py index 1a05c2d..494b702 100644 --- a/radio_beam/tests/test_beam.py +++ b/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) diff --git a/radio_beam/tests/test_beams.py b/radio_beam/tests/test_beams.py index 008e398..7e937f2 100644 --- a/radio_beam/tests/test_beams.py +++ b/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 diff --git a/radio_beam/utils.py b/radio_beam/utils.py index 8a58720..9590d82 100644 --- a/radio_beam/utils.py +++ b/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