Merge pull request #243 from MPoL-dev/WIP-v0.3

Library Reorganization for v0.3.0 release, first wave of commits around typing.

.github/workflows/docs_build.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: ["3.8"]
+        python-version: ["3.10"]
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python

.github/workflows/gh_docs.yml

@@ -13,7 +13,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.8'
+          python-version: '3.10'
       - name: Install doc deps
         run: |
           pip install .'[dev]'

.github/workflows/package.yml

@@ -14,7 +14,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: 3.8
+          python-version: 3.10
       - name: Install dependencies
         run: |
           pip install --upgrade pip

.github/workflows/pre-release.yml

@@ -13,7 +13,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: 3.8
+          python-version: "3.10"
       - name: Install package deps
         run: |
           pip install .[dev]
@@ -37,7 +37,7 @@ jobs:
       fail-fast: false
       max-parallel: 4
       matrix:
-        python-version: ["3.8", "3.9", "3.10"]
+        python-version: ["3.10", "3.11", "3.12"]
         os: [ubuntu-20.04, macOS-latest, windows-latest]
     steps:
       - uses: actions/checkout@v3

docs/changelog.md

@@ -3,7 +3,21 @@
 # Changelog
 
 ## v0.2.1
-
+- Made some progress converting docstrings from "Google" style format to "NumPy" style format. Ian is now convinced that NumPy style format is more readable for the type of docstrings we write in MPoL. We usually require long type definitions and long argument descriptions, and the extra indentation required for Google makes these very scrunched.
+- Make the `passthrough` behaviour of :class:`mpol.images.ImageCube` the default and removed this parameter entirely. Previously, it was possible to have :class:`mpol.images.ImageCube` act as a layer with `nn.Parameter`s. This functionality has effectively been replaced since the introduction of :class:`mpol.images.BaseCube` which provides a more useful way to parameterize pixel values. If a one-to-one mapping (including negative pixels) from `nn.Parameter`s to output tensor is desired, then one can specify `pixel_mapping=lambda x : x` when instantiating :class:`mpol.images.BaseCube`. More details in ([#246](https://github.com/MPoL-dev/MPoL/issues/246))
+- Removed convenience classmethods `from_image_properties` from across the code base. From [#233](https://github.com/MPoL-dev/MPoL/issues/233). The recommended workflow is to create a :class:`mpol.coordinates.GridCoords` object and pass that to instantiate these objects as needed, rather than passing `cell_size` and `npix` separately. For nearly all but trivially short workflows, this simplifies the number of variables the user needs to keep track and pass around revealing the central role of the :class:`mpol.coordinates.GridCoords` object and its useful attributes for image extent, visibility extent, etc. Most importantly, this significantly reduces the size of the codebase and the burden to maintain, test, and document multiple entry points to key `nn.modules`. We removed `from_image_properties` from
+  - :class:`mpol.datasets.GriddedDataset`
+  - :class:`mpol.datasets.Dartboard` 
+  - :class:`mpol.fourier.NuFFT`
+  - :class:`mpol.fourier.NuFFTCached` 
+  - :class:`mpol.fourier.FourierCube` 
+  - :class:`mpol.gridding.GridderBase` 
+  - :class:`mpol.gridding.DataAverager`
+  - :class:`mpol.gridding.DirtyImager`
+  - :class:`mpol.images.BaseCube`
+  - :class:`mpol.images.ImageCube`
+- Removed unused routine `mpol.utils.log_stretch`.
+- Added type hints for core modules ([#54](https://github.com/MPoL-dev/MPoL/issues/54)). This should improve stability of core routines and help users when writing code using MPoL in an IDE.
 - 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`.

docs/ci-tutorials/fakedata.md

@@ -253,7 +253,9 @@ img_tensor_packed = utils.sky_cube_to_packed_cube(img_tensor)
 
 ```{code-cell} ipython3
 from mpol.images import ImageCube
-image = ImageCube.from_image_properties(cell_size=cell_size, npix=npix, nchan=1, cube=img_tensor_packed)
+from mpol import coordinates
+coords = coordinates.GridCoords(cell_size=cell_size, npix=npix)
+image = ImageCube(coords=coords, nchan=1, cube=img_tensor_packed)
 ```
 
 If you want to double-check that the image was correctly inserted, you can do

docs/ci-tutorials/gridder.md

@@ -155,21 +155,7 @@ imager = gridding.DirtyImager(
 )
 ```
 
-Instantiating the {class}`~mpol.gridding.DirtyImager` object attaches the {class}`~mpol.coordinates.GridCoords`  object and the loose visibilities. There is also a convenience method to create the {class}`~mpol.coordinates.GridCoords` and {class}`~mpol.gridding.DirtyImager` object in one shot by
-
-```{code-cell}
-imager = gridding.DirtyImager.from_image_properties(
-    cell_size=0.005,  # [arcsec]
-    npix=800,
-    uu=uu,
-    vv=vv,
-    weight=weight,
-    data_re=data_re,
-    data_im=data_im,
-)
-```
-
-if you don't want to specify your {class}`~mpol.coordinates.GridCoords` object separately.
+Instantiating the {class}`~mpol.gridding.DirtyImager` object attaches the {class}`~mpol.coordinates.GridCoords`  object and the loose visibilities. 
 
 As we saw, the raw visibility dataset is a set of complex-valued Fourier samples. Our objective is to make images of the sky-brightness distribution and do astrophysics. We'll cover how to do this with MPoL and RML techniques in later tutorials, but it is possible to get a rough idea of the sky brightness by calculating the inverse Fourier transform of the visibility values.
 

docs/developer-documentation.md

@@ -168,15 +168,25 @@ In general, we envision the contribution lifecycle following a pattern:
 8. After the tests have completed successfully, use the Github interface to initiate a pull request back to the central repository. If you know that your feature branch isn't ready to be merged, but would still like feedback on your work, please submit a [draft or "work in progress"](https://github.blog/2019-02-14-introducing-draft-pull-requests/) pull request.
 9. Someone will review your pull request and may suggest additional changes for improvements. If approved, your pull request will be merged into the MPoL-dev/MPoL repo. Thank you for your contribution!
 
-### Contributing code and tests
+### Tests
 
 We strive to release a useable, stable software package. One way to help accomplish this is through writing rigorous and complete tests, especially after adding new functionality to the package. MPoL tests are located within the `test/` directory and follow [pytest](https://docs.pytest.org/en/6.2.x/contents.html#toc) conventions. Please add your new tests to this directory---we love new and useful tests.
 
 If you are adding new code functionality to the package, please make sure you have also written a set of corresponding tests probing the key interfaces. If you submit a pull request implementing code functionality without any new tests, be prepared for 'tests' to be one of the first suggestions on your pull request. Some helpful advice on *which* tests to write is [here](https://docs.python-guide.org/writing/tests/), [here](https://realpython.com/pytest-python-testing/), and [here](https://www.nerdwallet.com/blog/engineering/5-pytest-best-practices/).
 
 For MPoL maintainers, see instructions [here](https://github.com/MPoL-dev/MPoL/wiki/Releasing-a-new-version-of-MPoL) for releasing a new version of MPoL.
 
-### Contributing documentation
+### Typing
+
+Core MPoL routines are type-checked with [mypy](https://mypy.readthedocs.io/en/stable/index.html) for 100% coverage. Before you push your changes to the repo, you will want to make sure your code passes type checking locally (otherwise they will fail the GitHub Actions continuous integration tests). You can do this from the root of the repo by 
+
+```
+mypy src/mpol --pretty
+```
+
+If you are unfamiliar with typing in Python, we recommend reading the [mypy cheatsheet](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html) to get started.
+
+### Documentation
 
 A general workflow for writing documentation might look like
 

docs/large-tutorials/HD143006_part_1.md

@@ -150,11 +150,10 @@ The FITS image was a full 3000x3000 pixels. In general, it is good practice to s
 Since the DSHARP team has already checked there are no bright sub-mm sources in the FOV, we can save time and just make a smaller image corresponding to the protoplanetary emission. If `cell_size` is 0.003 arcseconds, `npix=512` pixels should be sufficient to make an image approximately 1.5 arcseconds on a side. Now, let's import the relevant MPoL routines and instantiate the Gridder.
 
 ```{code-cell}
-from mpol import gridding
+from mpol import coordinates, gridding
 
-imager = gridding.DirtyImager.from_image_properties(
-    cell_size=cell_size,
-    npix=512,
+coords = coordinates.GridCoords(cell_size=cell_size, npix=512)
+imager = gridding.DirtyImager(
     uu=uu,
     vv=vv,
     weight=weight,

pyproject.toml

@@ -23,7 +23,7 @@ description = "Regularized Maximum Likelihood Imaging for Radio Astronomy"
 dynamic = ["version"]
 name = "MPoL"
 readme = "README.md"
-requires-python = ">3.8"
+requires-python = ">=3.8"
 
 [project.optional-dependencies]
 dev = [
@@ -37,7 +37,7 @@ dev = [
     "frank>=1.2.1",
     "sphinx>=5.3.0",
     "jupytext",
-    "ipython!=8.7.0",               # broken version for syntax higlight https://github.com/spatialaudio/nbsphinx/issues/687
+    "ipython!=8.7.0", # broken version for syntax higlight https://github.com/spatialaudio/nbsphinx/issues/687
     "nbsphinx",
     "sphinx_book_theme>=0.9.3",
     "sphinx_copybutton",
@@ -72,4 +72,33 @@ source = "vcs"
 version-file = "src/mpol/mpol_version.py"
 
 [tool.black]
-line-length = 88
+line-length = 88
+
+[tool.mypy]
+warn_return_any = true
+warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+module = [
+    "astropy.*",
+    "matplotlib.*",
+    "scipy.*",
+    "torchkbnufft.*",
+    "frank.*",
+    "fast_histogram.*"
+]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = [
+    "MPoL.constants",
+    "MPoL.coordinates",
+    "MPoL.datasets",
+    # "MPoL.fourier", # once we remove get_vis_residuals
+    "MPoL.geometry",
+    # "MPoL.gridding", # once we sort check_data_inputs_2d
+    "MPoL.images",
+    "MPoL.losses"
+    # "MPoL.utils", # once we fix check_baselines
+    ]
+disallow_untyped_defs = true

src/mpol/constants.py

@@ -2,10 +2,10 @@
 from astropy.constants import c, k_B
 
 # convert from arcseconds to radians
-arcsec = np.pi / (180.0 * 3600)  # [radians]  = 1/206265 radian/arcsec
+arcsec: float = np.pi / (180.0 * 3600)  # [radians]  = 1/206265 radian/arcsec
 
-deg = np.pi / 180  # [radians]
+deg: float = np.pi / 180  # [radians]
 
-kB = k_B.cgs.value  # [erg K^-1] Boltzmann constant
-cc = c.cgs.value # [cm s^-1]
-c_ms = c.value # [m s^-1]
+kB: float = k_B.cgs.value  # [erg K^-1] Boltzmann constant
+cc: float = c.cgs.value  # [cm s^-1]
+c_ms: float = c.value  # [m s^-1]

src/mpol/coordinates.py

@@ -8,8 +8,7 @@
 
 import mpol.constants as const
 from mpol.exceptions import CellSizeError
-
-from .utils import get_max_spatial_freq, get_maximum_cell_size
+from mpol.utils import get_max_spatial_freq, get_maximum_cell_size
 
 
 class GridCoords: