Merge pull request #241 from MPoL-dev/linebreaks

Manually linewrap long docstrings.

.github/workflows/docs_build.yml

@@ -38,7 +38,7 @@ jobs:
           key: ${{ env.pythonLocation }}-${{ hashFiles('setup.py') }}
       - name: Install doc dependencies
         run: |
-          pip install .[docs]
+          pip install .[dev]
       - name: Install Pandoc dependency
         run: |
           sudo apt-get install pandoc

.github/workflows/gh_docs.yml

@@ -16,7 +16,7 @@ jobs:
           python-version: '3.8'
       - name: Install doc deps
         run: |
-          pip install .'[docs]'
+          pip install .'[dev]'
       - name: Install Pandoc dependency
         run: |
           sudo apt-get install pandoc

.pre-commit-config.yaml

@@ -2,13 +2,14 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+      - id: check-toml
       - id: check-added-large-files
-        args: ["--maxkb=5000"]
+        args: ["--maxkb=2000"]
       - id: detect-private-key
       - id: name-tests-test
   - repo: https://github.com/psf/black

docs/changelog.md

@@ -4,7 +4,8 @@
 
 ## v0.2.1
 
-- Fully leaned into the `pyproject.toml` setup to modernize build via [hatch](https://github.com/pypa/hatch). This centralizes the project dependencies and derives package versioning directly from git tags. Intermediate packages built from commits after the latest tag (e.g., `0.2.0`) will have an extra long string, e.g., `0.2.1.dev178+g16cfc3e.d20231223` where the version is a guess at the next version and the hash gives reference to the commit. This means that developers bump versions entirely by tagging a new version with git (or more likely by drafting a new release on the [GitHub release page](https://github.com/MPoL-dev/MPoL/releases)). 
+- Manually line wrapped many docstrings to conform to 88 characters per line or less. Ian thought `black` would do this by default, but actually that [doesn't seem to be the case](https://github.com/psf/black/issues/2865).
+- Fully leaned into the `pyproject.toml` setup to modernize build via [hatch](https://github.com/pypa/hatch). This centralizes the project dependencies and derives package versioning directly from git tags. Intermediate packages built from commits after the latest tag (e.g., `0.2.0`) will have an extra long string, e.g., `0.2.1.dev178+g16cfc3e.d20231223` where the version is a guess at the next version and the hash gives reference to the commit. This means that developers bump versions entirely by tagging a new version with git (or more likely by drafting a new release on the [GitHub release page](https://github.com/MPoL-dev/MPoL/releases)).
 - Removed `setup.py`.
 - TOML does not support adding keyed entries, so creating layered build environments of default, `docs`, `test`, and `dev` as we used to with `setup.py` is laborious and repetitive with `pyproject.toml`. We have simplified the list to be default (key dependencies), `test` (minimal necessary for test-suite), and `dev` (covering everything needed to build the docs and actively develop the package).
 - Removed custom `spheroidal_gridding` routines, tests, and the `UVDataset` object that used them. These have been superseded by the TorchKbNuFFT package. For reference, the old routines (including the tricky `corrfun` math) is preserved in a Gist [here](https://gist.github.com/iancze/f3d2769005a9e2c6731ee6977f166a83).
@@ -19,7 +20,7 @@
 - Reorganized some of the docs API
 - Expanded discussion and demonstration in `optimzation.md` tutorial
 - Localized harcoded Zenodo record reference to single instance, and created new external Zenodo record from which to draw
-- Added [Parametric inference with Pyro tutorial](large-tutorials/pyro.md) 
+- Added [Parametric inference with Pyro tutorial](large-tutorials/pyro.md)
 - Updated some discussion and notation in `rml_intro.md` tutorial
 - Added `mypy` static type checks
 - Added `frank` as a 'test' and 'analysis' extras dependency
@@ -30,7 +31,7 @@
 - Moved and rescoped {class}`~mpol.datasets.KFoldCrossValidatorGridded` to {class}`~mpol.crossval.DartboardSplitGridded` with some syntax changes
 - Altered {class}`~mpol.datasets.GriddedDataset` to subclass from `torch.nn.Module`, altered its args, added PyTorch buffers to it, added {func}`mpol.datasets.GriddedDataset.forward` to it
 - Added class method `from_image_properties` to various classes including {class}`~mpol.images.BaseCube` and {class}`~mpol.images.ImageCube`
-- Altered {class}`~mpol.datasets.UVDataset` to subclass from `torch.utils.data.Dataset`, altered its initialization signature, added new properties 
+- Altered {class}`~mpol.datasets.UVDataset` to subclass from `torch.utils.data.Dataset`, altered its initialization signature, added new properties
 - Altered {class}`~mpol.fourier.FourierCube` args and initialization signature, added PyTorch buffers to it
 - Added {func}`~mpol.fourier.get_vis_residuals`
 - Added new program `mpol.geometry` with new {func}`~mpol.geometry.flat_to_observer` and {func}`~mpol.geometry.observer_to_flat`

pyproject.toml

@@ -70,3 +70,6 @@ source = "vcs"
 
 [tool.hatch.build.hooks.vcs]
 version-file = "src/mpol/mpol_version.py"
+
+[tool.black]
+line-length = 88

src/mpol/coordinates.py

@@ -14,40 +14,67 @@
 
 class GridCoords:
     r"""
-    The GridCoords object uses desired image dimensions (via the ``cell_size`` and ``npix`` arguments) to define a corresponding Fourier plane grid.
+    The GridCoords object uses desired image dimensions (via the ``cell_size`` and 
+    ``npix`` arguments) to define a corresponding Fourier plane grid.
 
     Args:
         cell_size (float): width of a single square pixel in [arcsec]
         npix (int): number of pixels in the width of the image
 
-    The Fourier grid is defined over the domain :math:`[-u,+u]`, :math:`[-v,+v]`, even though for real images, technically we could use an RFFT grid from :math:`[0,+u]` to :math:`[-v,+v]`. The reason we opt for a full FFT grid in this instance is implementation simplicity.
+    The Fourier grid is defined over the domain :math:`[-u,+u]`, :math:`[-v,+v]`, even 
+    though for real images, technically we could use an RFFT grid from :math:`[0,+u]` to
+    :math:`[-v,+v]`. The reason we opt for a full FFT grid in this instance is 
+    implementation simplicity.
 
-    Images (and their corresponding Fourier transform quantities) are represented as two-dimensional arrays packed as ``[y, x]`` and ``[v, u]``.  This means that an image with dimensions ``(npix, npix)`` will also have a corresponding FFT Fourier grid with shape ``(npix, npix)``. The native :class:`~mpol.gridding.GridCoords` representation assumes the Fourier grid (and thus image) are laid out as one might normally expect an image (i.e., no ``np.fft.fftshift`` has been applied).
+    Images (and their corresponding Fourier transform quantities) are represented as 
+    two-dimensional arrays packed as ``[y, x]`` and ``[v, u]``.  This means that an 
+    image with dimensions ``(npix, npix)`` will also have a corresponding FFT Fourier 
+    grid with shape ``(npix, npix)``. The native :class:`~mpol.gridding.GridCoords` 
+    representation assumes the Fourier grid (and thus image) are laid out as one might 
+    normally expect an image (i.e., no ``np.fft.fftshift`` has been applied).
 
     After the object is initialized, instance variables can be accessed, for example
 
     >>> myCoords = GridCoords(cell_size=0.005, 512)
     >>> myCoords.img_ext
 
-    :ivar dl: image-plane cell spacing in RA direction (assumed to be positive) [radians]
+    :ivar dl: image-plane cell spacing in RA direction (assumed to be positive) 
+        [radians]
     :ivar dm: image-plane cell spacing in DEC direction [radians]
-    :ivar img_ext: The length-4 list of (left, right, bottom, top) expected by routines like ``matplotlib.pyplot.imshow`` in the ``extent`` parameter assuming ``origin='lower'``. Units of [arcsec]
-    :ivar packed_x_centers_2D: 2D array of l increasing, with fftshifted applied [arcseconds]. Useful for directly evaluating some function to create a packed cube.
-    :ivar packed_y_centers_2D: 2D array of m increasing, with fftshifted applied [arcseconds]. Useful for directly evaluating some function to create a packed cube.
-    :ivar sky_x_centers_2D: 2D array of l arranged for evaluating a sky image [arcseconds]. l coordinate increases to the left (as on sky).
-    :ivar sky_y_centers_2D: 2D array of m arranged for evaluating a sky image [arcseconds]. 
-    :ivar du: Fourier-plane cell spacing in East-West direction [:math:`\mathrm{k}\lambda`]
-    :ivar dv: Fourier-plane cell spacing in North-South direction [:math:`\mathrm{k}\lambda`]
-    :ivar u_centers: 1D array of cell centers in East-West direction [:math:`\mathrm{k}\lambda`].
-    :ivar v_centers: 1D array of cell centers in North-West direction [:math:`\mathrm{k}\lambda`].
-    :ivar u_edges: 1D array of cell edges in East-West direction [:math:`\mathrm{k}\lambda`].
-    :ivar v_edges: 1D array of cell edges in North-South direction [:math:`\mathrm{k}\lambda`].
+    :ivar img_ext: The length-4 list of (left, right, bottom, top) expected by routines 
+        like ``matplotlib.pyplot.imshow`` in the ``extent`` parameter assuming 
+        ``origin='lower'``. Units of [arcsec]
+    :ivar packed_x_centers_2D: 2D array of l increasing, with fftshifted applied 
+        [arcseconds]. Useful for directly evaluating some function to create a 
+        packed cube.
+    :ivar packed_y_centers_2D: 2D array of m increasing, with fftshifted applied 
+        [arcseconds]. Useful for directly evaluating some function to create a 
+        packed cube.
+    :ivar sky_x_centers_2D: 2D array of l arranged for evaluating a sky image 
+        [arcseconds]. l coordinate increases to the left (as on sky).
+    :ivar sky_y_centers_2D: 2D array of m arranged for evaluating a sky image 
+        [arcseconds]. 
+    :ivar du: Fourier-plane cell spacing in East-West direction 
+        [:math:`\mathrm{k}\lambda`]
+    :ivar dv: Fourier-plane cell spacing in North-South direction 
+        [:math:`\mathrm{k}\lambda`]
+    :ivar u_centers: 1D array of cell centers in East-West direction 
+        [:math:`\mathrm{k}\lambda`].
+    :ivar v_centers: 1D array of cell centers in North-West direction 
+        [:math:`\mathrm{k}\lambda`].
+    :ivar u_edges: 1D array of cell edges in East-West direction 
+        [:math:`\mathrm{k}\lambda`].
+    :ivar v_edges: 1D array of cell edges in North-South direction 
+        [:math:`\mathrm{k}\lambda`].
     :ivar u_bin_min: minimum u edge [:math:`\mathrm{k}\lambda`]
     :ivar u_bin_max: maximum u edge [:math:`\mathrm{k}\lambda`]
     :ivar v_bin_min: minimum v edge [:math:`\mathrm{k}\lambda`]
     :ivar v_bin_max: maximum v edge [:math:`\mathrm{k}\lambda`]
-    :ivar max_grid: maximum spatial frequency enclosed by Fourier grid [:math:`\mathrm{k}\lambda`]
-    :ivar vis_ext: length-4 list of (left, right, bottom, top) expected by routines like ``matplotlib.pyplot.imshow`` in the ``extent`` parameter assuming ``origin='lower'``. Units of [:math:`\mathrm{k}\lambda`]
+    :ivar max_grid: maximum spatial frequency enclosed by Fourier grid 
+        [:math:`\mathrm{k}\lambda`]
+    :ivar vis_ext: length-4 list of (left, right, bottom, top) expected by routines 
+        like ``matplotlib.pyplot.imshow`` in the ``extent`` parameter assuming 
+        ``origin='lower'``. Units of [:math:`\mathrm{k}\lambda`]
     """
 
     def __init__(self, cell_size: float, npix: int) -> None:
@@ -154,14 +181,19 @@ def __init__(self, cell_size: float, npix: int) -> None:
 
     def check_data_fit(self, uu: npt.ArrayLike, vv: npt.ArrayLike) -> None:
         r"""
-        Test whether loose data visibilities fit within the Fourier grid defined by cell_size and npix.
+        Test whether loose data visibilities fit within the Fourier grid defined by 
+        cell_size and npix.
 
         Args:
-            uu (np.array): array of u spatial frequency coordinates. Units of [:math:`\mathrm{k}\lambda`]
-            vv (np.array): array of v spatial frequency coordinates. Units of [:math:`\mathrm{k}\lambda`]
+            uu (np.array): array of u spatial frequency coordinates. 
+                Units of [:math:`\mathrm{k}\lambda`]
+            vv (np.array): array of v spatial frequency coordinates. 
+                Units of [:math:`\mathrm{k}\lambda`]
 
         Returns:
-            ``True`` if all visibilities fit within the Fourier grid defined by ``[u_bin_min, u_bin_max, v_bin_min, v_bin_max]``. Otherwise an ``AssertionError`` is raised on the first violated boundary.
+            ``True`` if all visibilities fit within the Fourier grid defined by 
+            ``[u_bin_min, u_bin_max, v_bin_min, v_bin_max]``. Otherwise an 
+            ``AssertionError`` is raised on the first violated boundary.
         """
 
         # max freq in dataset
@@ -185,6 +217,6 @@ def __eq__(self, other: Any) -> bool:
             # don't attempt to compare against different types
             return NotImplemented
 
-        # GridCoords objects are considered equal if they have the same cell_size and npix, since
-        # all other attributes are derived from these two core properties.
+        # GridCoords objects are considered equal if they have the same cell_size and 
+        # npix, since all other attributes are derived from these two core properties.
         return self.cell_size == other.cell_size and self.npix == other.npix