Merge pull request #3 from punch-mission/0.0.3

0.0.3

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         python -m pip install flake8 pytest pytest-cov hypothesis
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+        if [ -f requirements_dev.txt ]; then pip install -r requirements_dev.txt; fi
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names

README.md

@@ -3,17 +3,13 @@
 [![DOI](https://zenodo.org/badge/555583385.svg)](https://zenodo.org/badge/latestdoi/555583385)
 [![PyPI version](https://badge.fury.io/py/regularizepsf.svg)](https://badge.fury.io/py/regularizepsf)
 
-**UNDER DEVELOPMENT**
-
 A package for manipulating and correcting variable point spread functions.
 
 Below is an example of correcting model data using the package. An initial image of a simplified starfield (a) is synthetically observed with a slowly
 varying PSF (b), then regularized with this technique (c). The final image visually matches a direct convolution of
 the initial image with the target PSF (d). The panels are gamma-corrected to highlight the periphery of the model PSFs.
 ![Example result image](model_example.png)
 
-
-
 ## Getting started
 
 `pip install regularizepsf` and then follow along with the [Quickstart section](https://punch-mission.github.io/regularizepsf/quickstart.html). 
@@ -24,6 +20,9 @@ We encourage all contributions. If you have a problem with the code or would lik
 ## License
 See LICENSE for the MIT license
 
+## Need help?
+Please contact Marcus Hughes at [[email protected]](mailto:[email protected]).
+
 ## Citation
 Please cite the associated paper if you use this technique: 
 
@@ -47,6 +46,3 @@ Please cite the associated paper if you use this technique:
 }
 
 ```
-
-## Contact
-Please contact Marcus Hughes at [[email protected]](mailto:[email protected]) for any questions.

docs/_config.yml

@@ -1,13 +1,14 @@
 # Book settings
 # Learn more at https://jupyterbook.org/customize/config.html
 
-title: regularizepsf
+title: regularizePSF
 author: PUNCH Science Operations Center
 
 # Force re-execution of notebooks on each build.
 # See https://jupyterbook.org/content/execute.html
 execute:
   execute_notebooks: force
+  timeout: 100
 
 # Define the name of the latex output file for PDF builds
 latex:
@@ -20,10 +21,26 @@ bibtex_bibfiles:
 
 # Information about where the book exists on the web
 repository:
-  url: https://github.com/executablebooks/jupyter-book  # Online location of your book
+  url: https://github.com/punch-mission/regularizepsf  # Online location of your book
   path_to_book: docs  # Optional path to your book, relative to the repository root
   branch: main  # Which branch of the repository should be used when creating links (optional)
 
+parse:
+    # default extensions to enable in the myst parser.
+    # See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
+    myst_enable_extensions:
+        # - amsmath
+        - colon_fence
+        # - deflist
+        - dollarmath
+        - html_admonition
+        # - html_image
+        - linkify
+        # - replacements
+        # - smartquotes
+        - substitution
+    myst_url_schemes: [mailto, http, https] # URI schemes that will be recognised as external URLs in Markdown links
+
 # Add GitHub buttons to your book
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
 html:
@@ -36,7 +53,22 @@ sphinx:
   - 'sphinx.ext.napoleon'
   - 'sphinx.ext.viewcode'
   - 'sphinx.ext.autosummary'
+  - 'sphinx.ext.inheritance_diagram'
+  - 'autoapi.extension'
+  - "myst_nb"
+#  - 'sphinx_codeautolink'
   config:
+    html_show_copyright: false
     add_module_names: False
-    autosummary_generate: True
-
+    autoapi_dirs:
+      - "../regularizepsf"
+    autoapi_root: "api"
+    autoapi_add_toctree_entry: false
+    autoapi_keep_files: false
+    autoapi_options:
+      - "members"
+      - "undoc-members"
+      - "show-inheritance"
+      - "special-members"
+      - "imported-members"
+    autoapi_python_class_content: "both"

docs/_toc.yml

@@ -5,7 +5,9 @@ format: jb-book
 root: intro
 chapters:
 - file: quickstart
-- file: array
 - file: functional
 - file: theory
-- file: cite
+- file: cite
+- file: help
+- file: api/regularizepsf/index
+  title: API

docs/cite.md

@@ -1,23 +1,35 @@
 # How to cite
 
-Use the following Bibtex citation:
+To cite the paper:
 ```
-@misc{https://doi.org/10.48550/arxiv.2212.02594,
-  doi = {10.48550/ARXIV.2212.02594},
-  
-  url = {https://arxiv.org/abs/2212.02594},
-  
-  author = {Hughes, J. M. and DeForest, C. E. and Seaton, D. B.},
-  
-  keywords = {Instrumentation and Methods for Astrophysics (astro-ph.IM), FOS: Physical sciences, FOS: Physical sciences},
-  
-  title = {Coma Off It: Removing Variable Point Spread Functions from Astronomical Images},
-  
-  publisher = {arXiv},
-  
-  year = {2022},
-  
-  copyright = {arXiv.org perpetual, non-exclusive license}
+@ARTICLE{2022arXiv221202594H,
+       author = {{Hughes}, J.~M. and {DeForest}, C.~E. and {Seaton}, D.~B.},
+        title = "{Coma Off It: Removing Variable Point Spread Functions from Astronomical Images}",
+      journal = {arXiv e-prints},
+     keywords = {Astrophysics - Instrumentation and Methods for Astrophysics},
+         year = 2022,
+        month = dec,
+          eid = {arXiv:2212.02594},
+        pages = {arXiv:2212.02594},
+archivePrefix = {arXiv},
+       eprint = {2212.02594},
+ primaryClass = {astro-ph.IM},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2022arXiv221202594H},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
 }
+```
+
 
+To cite the software:
+```
+@software{marcus_hughes_2022_7392394,
+  author       = {Marcus Hughes},
+  title        = {punch-mission/regularizepsf: v0.0.3},
+  month        = dec,
+  year         = 2022,
+  publisher    = {Zenodo},
+  version      = {0.0.3},
+  doi          = {10.5281/zenodo.7392394},
+  url          = {https://doi.org/10.5281/zenodo.7392394}
+}
 ```

docs/functional.md

@@ -1 +1,113 @@
-# Correct using `FunctionalCorrector`
+# Correct using `FunctionalCorrector`
+A functional corrector is defined by a set of equations instead of image arrays. 
+The functional corrector can be helpful if you know the form of the PSF. You can directly define it. 
+
+```{note}
+To correct an image, a `FunctionalCorrector` will be converted to an `ArrayCorrector`. 
+If you plan to save a model for many corrections, you may find it more convenient to manually convert to an `ArrayCorrector`
+and then save an `ArrayConverter` instead. This is because a `FunctionalCorrector` merely pickles the functions using 
+`dill` while `ArrayCorrector` saves using HDF5. For more details, see the [Saving a corrector](save-corrector) section. 
+```
+
+## `simple_psf`: the starting point
+Every model begins with a `simple_psf`. It requires the first two arguments to be the `x` and `y` coordinates. 
+These will often be passed in as arrays so your function should operate in a vectorized manner and be able to output an
+array as well. 
+
+```py
+from regularizepsf import simple_psf
+
+@simple_psf
+def a_basic_example(x, y):
+    return x + y
+```
+You can always evaluate your PSF at a single point to determine its value:
+```py
+print(a_basic_example(101, 204))
+```
+Or you can evaluate at a variety of `x` and `y` coordinates using a `numpy` array. 
+```py
+print(a_basic_example(np.arange(100), np.arange(!00)))
+```
+
+You can then supply additional arguments with default values set. We will see in the next section
+how to use a `varied_psf` to make them vary across the field-of-view (FOV) of the image. 
+
+```py
+
+@simple_psf
+def with_default_arguments(x, y, width=100):
+    return x + y + width
+```
+
+## `varied_psf`: a more realistic model
+The purpose of this package is correct images with variable PSFs. Thus, we need a way to encode how the 
+PSF varies across the FOV. That's where `varied_psf` helps. The decorator requires a `simple_psf` as an argument. 
+We call this the base PSF. 
+Then, the function takes `x` and `y` as parameters and returns a dictionary of how the defaulted parameters of the base PSF vary. 
+
+For example, 
+```py
+from regularizepsf import simple_psf, varied_psf
+
+@simple_psf
+def base_psf(x, y, width=100):
+    return x + y + width
+
+@varied_psf(base_psf)
+def complicated_psf(x, y):
+    return {"width": x/(y+1)}
+```
+
+Now, the PSF's width will vary across an image and have the width of `x` divided by `y+1`. (We add one to avoid division
+by zero errors.)
+
+## Making a `FunctionalCorrector`
+Using these functionally defined examples, we can then create a `FunctionalCorrector` to correct an image. 
+
+```py
+from regularizepsf import FunctionalCorrector
+
+my_simple_corrector = FunctionalCorrector(base_psf)
+my_complicated_corrector = FunctionalCorrector(complicated_psf)
+```
+
+As discussed in the [Quickstart](quickstart.md), we often wish to correct our PSF to a uniform output by applying a 
+target PSF. We can provide that too!
+
+```py
+@simple_psf
+def target_psf(x, y):
+    return np.ones_like(x)
+
+my_corrector = FunctionalCorrector(complicated_psf, target_psf)
+```
+
+## Correcting an image
+Correcting an image is now trivial. We just load the image and correct with a specified patch size, 256 in this case. 
+```python
+from astropy.io import fits
+
+with fits.open("path_to_image.fits") as hdul:
+    data = hdul[0].data.astype(float)
+
+my_corrector.correct_image(data, 256)
+```
+
+```{note}
+If you're planning to do many corrections, you might first convert to an `ArrayCorrector`. The `FunctionalCorrector`'s
+`correct_image` function involves this step and would do it for each image. 
+```
+
+You can evaluate to an `ArrayCorrector` as shown below. The first argument is the `x`, then the `y`, and then the `size` of the patches. 
+```python
+new_corrector = my_corrector.evaluate_to_array_form(np.arange(256), np.arange(256), 256)
+```
+
+(save-corrector)=
+## Saving a corrector
+We can save a corrector in either its `FunctionalCorrector` form or its `ArrayCorrector` form.
+```python
+my_corrector.save("functional.psf")
+new_corrector.save("array.psf")
+```

docs/help.md

@@ -0,0 +1,7 @@
+# Getting help
+
+If you notice a bug, please open an issue on GitHub. 
+
+If you need help using this code, you can open an issue or contact Marcus Hughes directly at `[email protected]`. 
+We want to make this code as user-friendly as possible. If you're encountering an issue, it's likely someone else is too
+and you can help everyone by speaking up. Thanks for your support! 

docs/intro.md

@@ -1,13 +1,15 @@
-# Welcome to regularizepsf
+# Welcome
 
 `regularizepsf` is a Python package (with Cython speed improvements) for determining and correcting 
 point spread functions in astronomical images.
-It was originally developed for the [PUNCH](https://punch.space.swri.edu/) mission and is documented in an upcoming 
-Astrophysical Journal paper. For now, see [the arXiv listing](https://arxiv.org/abs/2212.02594). 
+It was originally developed for the [PUNCH](https://punch.space.swri.edu/) mission and is documented in a forthcoming 
+Astrophysical Journal paper (see [arXiv version](https://arxiv.org/abs/2212.02594) until publication). 
+
+Below is an example of correcting model data using the package. 
+An initial image of a simplified starfield (a) is synthetically observed with a slowly varying PSF (b), 
+then regularized with this technique (c). The final image visually matches a direct convolution of the initial image 
+with the target PSF (d). The panels are gamma-corrected to highlight the periphery of the model PSFs.
 
-Below is an example of correcting model data using the package. An initial image of a simplified starfield (a) is synthetically observed with a slowly
-varying PSF (b), then regularized with this technique (c). The final image visually matches a direct convolution of
-the initial image with the target PSF (d). The panels are gamma-corrected to highlight the periphery of the model PSFs.
 ```{image} images/model.png
 :alt: example of correction
 :width: 800px