Tighten up API, tidy docs, (#58)

* Tighten and tidy API, docs page per module and better tests
* Optonal args are now keyword only
* Use of qantity aware type annotations
* Doc refactor - page per submodule
* Fix bug in transform code
* Add fft equivalence test
* Fix WCS v array indexing errors
* Update mem and clean modules
* Fix type error for VisMeta

.pre-commit-config.yaml

@@ -27,6 +27,11 @@ repos:
         exclude: ".*(.fits|.fts|.fit|.header|.txt|tca.*|.json)$|^CITATION.rst$"
       - id: mixed-line-ending
         exclude: ".*(.fits|.fts|.fit|.header|.txt|tca.*)$"
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: "v1.10.0"
+    hooks:
+      - id: mypy
+        additional_dependencies: [ "types-setuptools" ]
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6
     hooks:

changelog/58.breaking.rst

@@ -0,0 +1,2 @@
+Optional parameters are now keyword only for the :mod:`xrayvision.transform`, :mod:`xrayvision.imaging` and :mod:`xrayvision.visibility` modules.
+Remove ``natural`` keyword in favour of ``scheme`` keyword which can be either 'natural' or 'uniform'.

changelog/58.bugfix.rst

@@ -0,0 +1 @@
+Fix a bug where the x, y dimensions were not being treated consistently in :mod:`xrayvision.transform`.

changelog/58.docs.rst

@@ -0,0 +1 @@
+Add per module reference pages, switch to documenting types using type annotations.

docs/conf.py

@@ -46,6 +46,9 @@
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
 
+# Set automodapi to generate files inside the generated directory
+automodapi_toctreedirnm = "generated/api"
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
@@ -63,14 +66,17 @@
 default_role = "obj"
 
 # Disable having a separate return type row
-napoleon_use_rtype = False
+napoleon_use_rtype = True
 
 # Disable google style docstrings
 napoleon_google_docstring = False
 
 # until sphinx-gallery / sphinx is fixed https://github.com/sphinx-doc/sphinx/issues/12300
 suppress_warnings = ["config.cache"]
 
+autodoc_typehints = "description"
+autoclass_content = "init"
+
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.

docs/reference/clean.rst

@@ -0,0 +1,8 @@
+.. _clean:
+
+Clean ('xrayvision.clean')
+**************************
+
+The ``clean`` submodule contains clean imaging methods.
+
+.. automodapi:: xrayvision.clean

docs/reference/imaging.rst

@@ -0,0 +1,8 @@
+.. _imaging:
+
+Imaging ('xrayvision.imaging')
+******************************
+
+The ``imaging`` submodule contains functions to make map and images from visibilities.
+
+.. automodapi:: xrayvision.imaging

docs/reference/index.rst

@@ -1,23 +1,15 @@
-.. _reference:
-
 *********
 Reference
 *********
 
-.. automodapi:: xrayvision.visibility
-
-.. automodapi:: xrayvision.imaging
-
-.. automodapi:: xrayvision.transform
-
-.. automodapi:: xrayvision.clean
-
-.. automodapi:: xrayvision.mem
-
-.. automodapi:: xrayvision.utils
-
-
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+
+   clean
+   imaging
+   mem
+   transform
+   utils
+   visibility
 
    ../whatsnew/index

docs/reference/mem.rst

@@ -0,0 +1,8 @@
+.. _mem:
+
+MEM ('xrayvision.mem')
+**********************
+
+The ``mem`` submodule contains the Maximum Entropy methods.
+
+.. automodapi:: xrayvision.mem

docs/reference/transform.rst

@@ -0,0 +1,8 @@
+.. _transform:
+
+Transform ('xrayvision.transform')
+**********************************
+
+The ``transform`` submodule forward and reverse transforms.
+
+.. automodapi:: xrayvision.transform

docs/reference/utils.rst

@@ -0,0 +1,8 @@
+.. _utils:
+
+Utils ('xrayvision.utils')
+**************************
+
+The ``utils`` submodule contains utility functions.
+
+.. automodapi:: xrayvision.utils

docs/reference/visibility.rst

@@ -0,0 +1,8 @@
+.. _visibility:
+
+Visibility ('xrayvision.visibility')
+************************************
+
+The ``visibility`` submodule contains generic visibility classes.
+
+.. automodapi:: xrayvision.visibility

docs/tutorials/introduction.rst

@@ -41,10 +41,10 @@ measured visibilities in f can the original map a be recovered?
 
     data = make_data()
 
-    full_uv = transform.generate_uv(65)
+    full_uv = transform.generate_uv(65*u.pix)
 
-    uu = transform.generate_uv(33)
-    vv = transform.generate_uv(33)
+    uu = transform.generate_uv(33*u.pix)
+    vv = transform.generate_uv(33*u.pix)
 
     uu, vv = np.meshgrid(uu, vv)
 
@@ -53,7 +53,7 @@ measured visibilities in f can the original map a be recovered?
 
     full_vis = transform.dft_map(data, u=uv[0,:], v=uv[1,:])
 
-    res = transform.idft_map(full_vis, u=uv[0,:], v=uv[1,:], shape=(33, 33))
+    res = transform.idft_map(full_vis, u=uv[0,:], v=uv[1,:], weights=1/33**2, shape=(33, 33)*u.pix)
     # assert np.allclose(data, res)
 
     # Generate log spaced radial u, v sampeling
@@ -77,9 +77,10 @@ measured visibilities in f can the original map a be recovered?
     sub_vis = transform.dft_map(data, u=sub_uv[0,:], v=sub_uv[1,:])
 
     psf1 = transform.idft_map(np.full(sub_vis.size, 1), u=sub_uv[0,:], v=sub_uv[1,:],
-                              shape=(65, 65))
+                              weights=1/sub_vis.size, shape=(65, 65)*u.pix)
 
-    sub_res = transform.idft_map(sub_vis, u=sub_uv[0,:], v=sub_uv[1,:], shape=(65, 65))
+    sub_res = transform.idft_map(sub_vis, u=sub_uv[0,:], v=sub_uv[1,:],
+                                 weights=1/sub_vis.size, shape=(65, 65)*u.pix)
 
     xp = np.round(x * 33 + 33/2 - 0.5 + 16).astype(int)
     yp = np.round(y * 33 + 33/2 - 0.5 + 16).astype(int)

examples/rhessi.py

@@ -64,13 +64,13 @@
 ###############################################################################
 # Lets have a look at the point spread function (PSF) or dirty beam
 
-psf_map = vis_psf_map(vis, shape=(101, 101) * apu.pixel, pixel_size=1.5 * apu.arcsec, natural=False)
+psf_map = vis_psf_map(vis, shape=(101, 101) * apu.pixel, pixel_size=1.5 * apu.arcsec / apu.pixel, scheme="uniform")
 
 ###############################################################################
 # We can now make an image using the back projection algorithm essentially and
 # inverse Fourier transform of the visibilities.
 
-backproj_map = vis_to_map(vis, shape=[101, 101] * apu.pixel, pixel_size=1.5 * apu.arcsec)
+backproj_map = vis_to_map(vis, shape=[101, 101] * apu.pixel, pixel_size=1.5 * apu.arcsec / apu.pix)
 
 ###############################################################################
 # Back projection contain many artifact due to the incomplete sampling of the u-v
@@ -83,13 +83,17 @@
 #                     v=vis_data_59['v']/apu.arcsec, offset=vis_data_59['xyoffset'][0]*apu.arcsec)
 
 clean_map, model_map, residual_map = vis_clean(
-    vis, shape=[101, 101] * apu.pixel, pixel=[1.5, 1.5] * apu.arcsec, clean_beam_width=10 * apu.arcsec, niter=100
+    vis,
+    shape=[101, 101] * apu.pixel,
+    pixel_size=[1.5, 1.5] * apu.arcsec / apu.pix,
+    clean_beam_width=10 * apu.arcsec,
+    niter=100,
 )
 
 ###############################################################################
 # MEM
 
-mem_map = mem(vis, shape=[129, 129] * apu.pixel, pixel=[2, 2] * apu.arcsec)
+mem_map = mem(vis, shape=[129, 129] * apu.pixel, pixel_size=[2, 2] * apu.arcsec / apu.pix)
 mem_map.plot()
 
 

examples/stix.py

@@ -26,32 +26,37 @@
 stix_data = pickle.load(urllib.request.urlopen("https://pub099.cs.technik.fhnw.ch/demo/stix_vis.pkl"))
 
 time_range, energy_range, offset, stix_vis = stix_data
+stix_vis.phase_centre = [0, 0] * apu.arcsec
 stix_vis.offset = offset
 
 ###############################################################################
 # Lets have a look at the point spread function (PSF) or dirty beam
 
-psf_map = vis_psf_map(stix_vis, shape=(129, 129) * apu.pixel, pixel_size=2 * apu.arcsec, natural=False)
+psf_map = vis_psf_map(stix_vis, shape=(129, 129) * apu.pixel, pixel_size=2 * apu.arcsec / apu.pix, scheme="uniform")
 psf_map.plot()
 
 ###############################################################################
 # Back projection
 
-backproj_map = vis_to_map(stix_vis, shape=(129, 129) * apu.pixel, pixel_size=2 * apu.arcsec, natural=False)
+backproj_map = vis_to_map(stix_vis, shape=(129, 129) * apu.pixel, pixel_size=2 * apu.arcsec / apu.pix, scheme="uniform")
 backproj_map.plot()
 
 ###############################################################################
 # Clean
 
 clean_map, model_map, resid_map = vis_clean(
-    stix_vis, shape=[129, 129] * apu.pixel, pixel=[2, 2] * apu.arcsec, niter=100, clean_beam_width=20 * apu.arcsec
+    stix_vis,
+    shape=[129, 129] * apu.pixel,
+    pixel_size=[2, 2] * apu.arcsec / apu.pix,
+    clean_beam_width=20 * apu.arcsec,
+    niter=100,
 )
 clean_map.plot()
 
 ###############################################################################
 # MEM
 
-mem_map = mem(stix_vis, shape=[129, 129] * apu.pixel, pixel=[2, 2] * apu.arcsec)
+mem_map = mem(stix_vis, shape=[129, 129] * apu.pixel, pixel_size=[2, 2] * apu.arcsec / apu.pix)
 mem_map.plot()
 
 ###############################################################################

setup.cfg

@@ -97,6 +97,9 @@ ignore-words-list =
     process,
     technik
 
+[mypy]
+disable_error_code = import-untyped
+
 [coverage:run]
 omit =
   xrayvision/_sunpy_init*

xrayvision/__init__.py

@@ -1,11 +1,7 @@
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
 
 try:
-    from xrayvision.version import __version__
+    from xrayvision.version import __version__  # type: ignore
 except ImportError:
     __version__ = "unknown"
-__all__ = []
-
-from pkg_resources import resource_filename
-
-SAMPLE_RHESSI_VISIBILITIES = resource_filename("xrayvision", "data/hsi_visibili_20131028_0156_20131028_0200_6_12.fits")
+__all__: list[str] = []