jwst-psfmc 0.1.0__tar.gz

jwst_psfmc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mingyang Zhuang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jwst_psfmc-0.1.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: jwst-psfmc
+Version: 0.1.0
+Summary: PSF photometry with MCMC for JWST (and HST) drizzled difference images, with correlated-noise likelihood
+Author: Mingyang Zhuang
+License: MIT
+Project-URL: Homepage, https://github.com/mingyangzhuang/jwst_psfmc
+Project-URL: Bug Tracker, https://github.com/mingyangzhuang/jwst_psfmc/issues
+Keywords: astronomy,JWST,PSF,photometry,MCMC,drizzle,transients,supernovae
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.9
+Requires-Dist: astropy>=5.2
+Requires-Dist: photutils>=1.7
+Requires-Dist: emcee>=3.1
+Requires-Dist: corner>=2.2
+Requires-Dist: matplotlib>=3.6
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Dynamic: license-file
+
+# jwst_psfmc
+
+**PSF photometry with MCMC for JWST (and HST) drizzled difference images.**
+
+[![CI](https://github.com/mingyangzhuang/jwst_psfmc/actions/workflows/ci.yml/badge.svg)](https://github.com/mingyangzhuang/jwst_psfmc/actions)
+[![PyPI](https://img.shields.io/pypi/v/jwst-psfmc)](https://pypi.org/project/jwst-psfmc/)
+[![Python](https://img.shields.io/pypi/pyversions/jwst-psfmc)](https://pypi.org/project/jwst-psfmc/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Scientific Background
+
+JWST NIRCam images processed with the [drizzle algorithm](https://drizzlepac.readthedocs.io)
+exhibit **spatially correlated pixel-to-pixel noise**: photons detected in a single detector
+pixel are spread across several output pixels during co-addition.  If these correlations are
+ignored in a standard χ² PSF fit, the flux uncertainties are systematically *underestimated*.
+  Even in full MCMC fitting with correlated-noise likelihoods, neglecting the covariance kernel
+  underestimates flux uncertainties by ~30% in F200W (Zhuang et al., *NEXUS: Transient Searches
+  and First Results from Year One Observations*, in prep.).
+
+`jwst_psfmc` solves this by:
+
+1. **Measuring the covariance structure** directly from source-free sky regions of the
+   difference image using an autocorrelation estimator.
+2. **Encoding the covariance as a Fourier-space power spectrum**, enabling an exact
+   correlated-noise log-likelihood that is *O(N log N)* per MCMC step.
+3. **Running an ensemble MCMC sampler** ([`emcee`](https://emcee.readthedocs.io)) to obtain
+   full posterior distributions for the four model parameters:
+
+   | Parameter | Description |
+   |-----------|-------------|
+   | `flux`    | Total source flux (same units as the image) |
+   | `dx`      | Sub-pixel x-shift of the PSF centroid (native pixels) |
+   | `dy`      | Sub-pixel y-shift of the PSF centroid (native pixels) |
+   | `bkg`     | Flat residual background level |
+
+The PSF is shifted with **exact Fourier-space interpolation** (no interpolation kernel
+artefacts) and downsampled from the 4× oversampled PSF model by block-summing.
+
+---
+
+## Installation
+
+```bash
+pip install jwst-psfmc
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/mingyangzhuang/jwst_psfmc.git
+cd jwst_psfmc
+pip install -e ".[dev]"
+```
+
+**Dependencies:** `numpy`, `scipy`, `astropy`, `photutils`, `emcee`, `corner`, `matplotlib`
+
+---
+
+## Example Data
+
+The example FITS files (difference images, error maps, covariance kernels, and PSF models)
+live in `examples/data/` and `examples/PSF/` inside the repository. They are **not**
+bundled with the PyPI package — clone the repo to use them:
+
+```bash
+git clone https://github.com/mingyangzhuang/jwst_psfmc.git
+cd jwst_psfmc/examples
+jupyter notebook demo_psf_photometry.ipynb
+```
+
+| File | Description |
+|------|-------------|
+| `examples/data/example1_f200w_diff.fits` | Difference image — non-detection |
+| `examples/data/example1_f200w_diff_error.fits` | Uncertainty map — non-detection |
+| `examples/data/example1_f200w_cov_kernel.fits` | Covariance kernel — non-detection |
+| `examples/data/example2_f200w_diff.fits` | Difference image — detection |
+| `examples/data/example2_f200w_diff_error.fits` | Uncertainty map — detection |
+| `examples/data/example2_f200w_cov_kernel.fits` | Covariance kernel — detection |
+| `examples/PSF/example1_f200w_PSF_4_c.fits` | 4× oversampled PSF model — non-detection |
+| `examples/PSF/example2_f200w_PSF_4_c.fits` | 4× oversampled PSF model — detection |
+
+---
+
+## Quick Start
+
+The core API accepts NumPy arrays directly — load your own FITS files however you prefer:
+
+```python
+from astropy.io import fits
+import numpy as np
+import jwst_psfmc as jpm
+
+# ── 1. Load your data ──────────────────────────────────────────────────────
+data    = fits.getdata("examples/data/example2_f200w_diff.fits")
+err     = fits.getdata("examples/data/example2_f200w_diff_error.fits")
+kernel  = fits.getdata("examples/data/example2_f200w_cov_kernel.fits")
+psf_raw = fits.getdata("examples/PSF/example2_f200w_PSF_4_c.fits")
+
+# ── 2. Extract a 9×9 stamp centred on the source ───────────────────────────
+cy, cx = data.shape[0] // 2, data.shape[1] // 2
+stamp     = data[cy-4:cy+5, cx-4:cx+5]
+stamp_err = err[cy-4:cy+5, cx-4:cx+5]
+
+# ── 3. Prepare MCMC inputs ─────────────────────────────────────────────────
+fit_args = jpm.prepare_for_fitting(
+    data=stamp, err=stamp_err,
+    psf_os=psf_raw, cov_kernel=kernel,
+    dx_init=0.0, dy_init=0.0,
+    oversamp=4, native_shape=(11, 11), nwalkers=48,
+)
+
+# ── 4. Run MCMC ────────────────────────────────────────────────────────────
+sampler = jpm.run_mcmc(**fit_args, nsteps=2000, ncores=4, progress=True)
+
+# ── 5. Summarise posterior ─────────────────────────────────────────────────
+summary = jpm.summarize_emcee(sampler, burnin=500, thin=4)
+print(f"flux = {summary['flux']['median']:.4f} "
+      f"+{summary['flux']['plus_1sigma']:.4f} / "
+      f"-{summary['flux']['minus_1sigma']:.4f}")
+
+# ── 6. Visualise ───────────────────────────────────────────────────────────
+fig_trip, _ = jpm.plot_psf_fit_triptych(
+    stamp, stamp_err, fit_args["psf_os"], oversamp=4,
+    native_shape=fit_args["native_shape"],
+    psf_prepare_fraction=fit_args["psf_prepare_fraction"],
+    summary=summary, fig_title="Detection example — F200W",
+)
+fig_trip.savefig("triptych.pdf", bbox_inches="tight")
+
+fig_chains, _ = jpm.plot_chains(sampler, burnin=500)
+fig_corner, _ = jpm.plot_corner(sampler, burnin=500, thin=4)
+
+# ── 7. Save / reload results ───────────────────────────────────────────────
+jpm.save_emcee_results("example2_f200w_mcmc.npz", sampler)
+res = jpm.load_emcee_results("example2_f200w_mcmc.npz")
+print(res["summary"])
+```
+
+### Deriving a flux upper limit from a non-detection
+
+Residual small-scale background fluctuations can mimic low-level source
+emission at 1–2σ. We use a **two-run workflow**:
+
+1. **Detection check** — broad priors (±1 pix on dx/dy) to confirm the
+   source is genuinely absent.
+2. **Upper limit** — tight priors (±0.1 pix) to derive the official 3σ
+   bound from the 99.7th percentile of the posterior flux.
+
+```python
+data_nd   = fits.getdata("examples/data/example1_f200w_diff.fits")
+err_nd    = fits.getdata("examples/data/example1_f200w_diff_error.fits")
+kernel_nd = fits.getdata("examples/data/example1_f200w_cov_kernel.fits")
+psf_nd    = fits.getdata("examples/PSF/example1_f200w_PSF_4_c.fits")
+
+stamp_nd     = data_nd[cy-4:cy+5, cx-4:cx+5]
+stamp_err_nd = err_nd[cy-4:cy+5, cx-4:cx+5]
+
+# ── Run 1: broad priors (detection check) ─────────────────────────────
+fit_nd_broad = jpm.prepare_for_fitting(data=stamp_nd, err=stamp_err_nd,
+                                       psf_os=psf_nd, cov_kernel=kernel_nd)
+sampler_nd_broad = jpm.run_mcmc(**fit_nd_broad, nsteps=2000, ncores=4,
+                                progress=True)
+
+# Confirm non-detection: flux median consistent with zero within 1σ
+summary_broad = jpm.summarize_emcee(sampler_nd_broad, burnin=500, thin=4)
+is_absent = abs(summary_broad['flux']['median']) < summary_broad['flux']['plus_1sigma']
+print(f'Non-detection confirmed: {is_absent}')
+
+# ── Run 2: tight priors (upper limit) ─────────────────────────────────
+fit_nd_tight = jpm.prepare_for_fitting(data=stamp_nd, err=stamp_err_nd,
+                                       psf_os=psf_nd, cov_kernel=kernel_nd,
+                                       pos_prior_half_width=0.1)  # ±0.1 pix
+sampler_nd_tight = jpm.run_mcmc(**fit_nd_tight, nsteps=2000, ncores=4,
+                                progress=True)
+
+flat_flux = sampler_nd_tight.get_chain(discard=500, thin=4, flat=True)[:, 0]
+upper_limit_3sigma = float(np.percentile(flat_flux, 99.7))
+print(f"3-sigma upper limit on flux: {upper_limit_3sigma:.4f}")
+```
+
+---
+
+## Full Worked Examples
+
+### Covariance kernel estimation
+
+See **[`examples/demo_covariance_kernel.ipynb`](examples/demo_covariance_kernel.ipynb)** for
+a step-by-step demonstration of estimating the pixel-to-pixel covariance kernel
+from JWST difference images:
+
+- Source masking and finding source-free sky regions
+- Autocorrelation-based kernel estimation
+- Cosine-bell windowing and power spectrum computation
+- Pixel correlation whitening demonstration
+
+### PSF photometry with MCMC
+
+See **[`examples/demo_psf_photometry.ipynb`](examples/demo_psf_photometry.ipynb)** for a
+step-by-step notebook covering:
+
+- Loading and inspecting the JWST cutout data
+- Estimating and visualising the covariance kernel
+- Running MCMC for a **non-detection** (example1) and deriving a rigorous 3-σ upper limit
+- Running MCMC for a clear **detection** (example2) and extracting flux posteriors
+- Diagnosing convergence via chain traces and autocorrelation times
+- Producing publication-quality corner plots and residual triptychs
+
+---
+
+## Module Overview
+
+| Module | Contents |
+|--------|----------|
+| `jwst_psfmc.psf` | PSF shifting, downsampling, model evaluation |
+| `jwst_psfmc.covariance` | Covariance kernel estimation, Fourier-space pre-computation |
+| `jwst_psfmc.mcmc` | MCMC preparation, log-prob, `run_mcmc`, posterior summaries |
+| `jwst_psfmc.io` | Save/load `.npz` results |
+| `jwst_psfmc.plot` | Triptych, chain traces, corner plot |
+
+---
+
+## Citation
+
+If you use `jwst_psfmc` in your research, please cite:
+
+> Zhuang et al. (in prep.), *NEXUS JWST Transient Survey Year 1*
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

jwst_psfmc-0.1.0/README.md

@@ -0,0 +1,234 @@
+# jwst_psfmc
+
+**PSF photometry with MCMC for JWST (and HST) drizzled difference images.**
+
+[![CI](https://github.com/mingyangzhuang/jwst_psfmc/actions/workflows/ci.yml/badge.svg)](https://github.com/mingyangzhuang/jwst_psfmc/actions)
+[![PyPI](https://img.shields.io/pypi/v/jwst-psfmc)](https://pypi.org/project/jwst-psfmc/)
+[![Python](https://img.shields.io/pypi/pyversions/jwst-psfmc)](https://pypi.org/project/jwst-psfmc/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Scientific Background
+
+JWST NIRCam images processed with the [drizzle algorithm](https://drizzlepac.readthedocs.io)
+exhibit **spatially correlated pixel-to-pixel noise**: photons detected in a single detector
+pixel are spread across several output pixels during co-addition.  If these correlations are
+ignored in a standard χ² PSF fit, the flux uncertainties are systematically *underestimated*.
+  Even in full MCMC fitting with correlated-noise likelihoods, neglecting the covariance kernel
+  underestimates flux uncertainties by ~30% in F200W (Zhuang et al., *NEXUS: Transient Searches
+  and First Results from Year One Observations*, in prep.).
+
+`jwst_psfmc` solves this by:
+
+1. **Measuring the covariance structure** directly from source-free sky regions of the
+   difference image using an autocorrelation estimator.
+2. **Encoding the covariance as a Fourier-space power spectrum**, enabling an exact
+   correlated-noise log-likelihood that is *O(N log N)* per MCMC step.
+3. **Running an ensemble MCMC sampler** ([`emcee`](https://emcee.readthedocs.io)) to obtain
+   full posterior distributions for the four model parameters:
+
+   | Parameter | Description |
+   |-----------|-------------|
+   | `flux`    | Total source flux (same units as the image) |
+   | `dx`      | Sub-pixel x-shift of the PSF centroid (native pixels) |
+   | `dy`      | Sub-pixel y-shift of the PSF centroid (native pixels) |
+   | `bkg`     | Flat residual background level |
+
+The PSF is shifted with **exact Fourier-space interpolation** (no interpolation kernel
+artefacts) and downsampled from the 4× oversampled PSF model by block-summing.
+
+---
+
+## Installation
+
+```bash
+pip install jwst-psfmc
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/mingyangzhuang/jwst_psfmc.git
+cd jwst_psfmc
+pip install -e ".[dev]"
+```
+
+**Dependencies:** `numpy`, `scipy`, `astropy`, `photutils`, `emcee`, `corner`, `matplotlib`
+
+---
+
+## Example Data
+
+The example FITS files (difference images, error maps, covariance kernels, and PSF models)
+live in `examples/data/` and `examples/PSF/` inside the repository. They are **not**
+bundled with the PyPI package — clone the repo to use them:
+
+```bash
+git clone https://github.com/mingyangzhuang/jwst_psfmc.git
+cd jwst_psfmc/examples
+jupyter notebook demo_psf_photometry.ipynb
+```
+
+| File | Description |
+|------|-------------|
+| `examples/data/example1_f200w_diff.fits` | Difference image — non-detection |
+| `examples/data/example1_f200w_diff_error.fits` | Uncertainty map — non-detection |
+| `examples/data/example1_f200w_cov_kernel.fits` | Covariance kernel — non-detection |
+| `examples/data/example2_f200w_diff.fits` | Difference image — detection |
+| `examples/data/example2_f200w_diff_error.fits` | Uncertainty map — detection |
+| `examples/data/example2_f200w_cov_kernel.fits` | Covariance kernel — detection |
+| `examples/PSF/example1_f200w_PSF_4_c.fits` | 4× oversampled PSF model — non-detection |
+| `examples/PSF/example2_f200w_PSF_4_c.fits` | 4× oversampled PSF model — detection |
+
+---
+
+## Quick Start
+
+The core API accepts NumPy arrays directly — load your own FITS files however you prefer:
+
+```python
+from astropy.io import fits
+import numpy as np
+import jwst_psfmc as jpm
+
+# ── 1. Load your data ──────────────────────────────────────────────────────
+data    = fits.getdata("examples/data/example2_f200w_diff.fits")
+err     = fits.getdata("examples/data/example2_f200w_diff_error.fits")
+kernel  = fits.getdata("examples/data/example2_f200w_cov_kernel.fits")
+psf_raw = fits.getdata("examples/PSF/example2_f200w_PSF_4_c.fits")
+
+# ── 2. Extract a 9×9 stamp centred on the source ───────────────────────────
+cy, cx = data.shape[0] // 2, data.shape[1] // 2
+stamp     = data[cy-4:cy+5, cx-4:cx+5]
+stamp_err = err[cy-4:cy+5, cx-4:cx+5]
+
+# ── 3. Prepare MCMC inputs ─────────────────────────────────────────────────
+fit_args = jpm.prepare_for_fitting(
+    data=stamp, err=stamp_err,
+    psf_os=psf_raw, cov_kernel=kernel,
+    dx_init=0.0, dy_init=0.0,
+    oversamp=4, native_shape=(11, 11), nwalkers=48,
+)
+
+# ── 4. Run MCMC ────────────────────────────────────────────────────────────
+sampler = jpm.run_mcmc(**fit_args, nsteps=2000, ncores=4, progress=True)
+
+# ── 5. Summarise posterior ─────────────────────────────────────────────────
+summary = jpm.summarize_emcee(sampler, burnin=500, thin=4)
+print(f"flux = {summary['flux']['median']:.4f} "
+      f"+{summary['flux']['plus_1sigma']:.4f} / "
+      f"-{summary['flux']['minus_1sigma']:.4f}")
+
+# ── 6. Visualise ───────────────────────────────────────────────────────────
+fig_trip, _ = jpm.plot_psf_fit_triptych(
+    stamp, stamp_err, fit_args["psf_os"], oversamp=4,
+    native_shape=fit_args["native_shape"],
+    psf_prepare_fraction=fit_args["psf_prepare_fraction"],
+    summary=summary, fig_title="Detection example — F200W",
+)
+fig_trip.savefig("triptych.pdf", bbox_inches="tight")
+
+fig_chains, _ = jpm.plot_chains(sampler, burnin=500)
+fig_corner, _ = jpm.plot_corner(sampler, burnin=500, thin=4)
+
+# ── 7. Save / reload results ───────────────────────────────────────────────
+jpm.save_emcee_results("example2_f200w_mcmc.npz", sampler)
+res = jpm.load_emcee_results("example2_f200w_mcmc.npz")
+print(res["summary"])
+```
+
+### Deriving a flux upper limit from a non-detection
+
+Residual small-scale background fluctuations can mimic low-level source
+emission at 1–2σ. We use a **two-run workflow**:
+
+1. **Detection check** — broad priors (±1 pix on dx/dy) to confirm the
+   source is genuinely absent.
+2. **Upper limit** — tight priors (±0.1 pix) to derive the official 3σ
+   bound from the 99.7th percentile of the posterior flux.
+
+```python
+data_nd   = fits.getdata("examples/data/example1_f200w_diff.fits")
+err_nd    = fits.getdata("examples/data/example1_f200w_diff_error.fits")
+kernel_nd = fits.getdata("examples/data/example1_f200w_cov_kernel.fits")
+psf_nd    = fits.getdata("examples/PSF/example1_f200w_PSF_4_c.fits")
+
+stamp_nd     = data_nd[cy-4:cy+5, cx-4:cx+5]
+stamp_err_nd = err_nd[cy-4:cy+5, cx-4:cx+5]
+
+# ── Run 1: broad priors (detection check) ─────────────────────────────
+fit_nd_broad = jpm.prepare_for_fitting(data=stamp_nd, err=stamp_err_nd,
+                                       psf_os=psf_nd, cov_kernel=kernel_nd)
+sampler_nd_broad = jpm.run_mcmc(**fit_nd_broad, nsteps=2000, ncores=4,
+                                progress=True)
+
+# Confirm non-detection: flux median consistent with zero within 1σ
+summary_broad = jpm.summarize_emcee(sampler_nd_broad, burnin=500, thin=4)
+is_absent = abs(summary_broad['flux']['median']) < summary_broad['flux']['plus_1sigma']
+print(f'Non-detection confirmed: {is_absent}')
+
+# ── Run 2: tight priors (upper limit) ─────────────────────────────────
+fit_nd_tight = jpm.prepare_for_fitting(data=stamp_nd, err=stamp_err_nd,
+                                       psf_os=psf_nd, cov_kernel=kernel_nd,
+                                       pos_prior_half_width=0.1)  # ±0.1 pix
+sampler_nd_tight = jpm.run_mcmc(**fit_nd_tight, nsteps=2000, ncores=4,
+                                progress=True)
+
+flat_flux = sampler_nd_tight.get_chain(discard=500, thin=4, flat=True)[:, 0]
+upper_limit_3sigma = float(np.percentile(flat_flux, 99.7))
+print(f"3-sigma upper limit on flux: {upper_limit_3sigma:.4f}")
+```
+
+---
+
+## Full Worked Examples
+
+### Covariance kernel estimation
+
+See **[`examples/demo_covariance_kernel.ipynb`](examples/demo_covariance_kernel.ipynb)** for
+a step-by-step demonstration of estimating the pixel-to-pixel covariance kernel
+from JWST difference images:
+
+- Source masking and finding source-free sky regions
+- Autocorrelation-based kernel estimation
+- Cosine-bell windowing and power spectrum computation
+- Pixel correlation whitening demonstration
+
+### PSF photometry with MCMC
+
+See **[`examples/demo_psf_photometry.ipynb`](examples/demo_psf_photometry.ipynb)** for a
+step-by-step notebook covering:
+
+- Loading and inspecting the JWST cutout data
+- Estimating and visualising the covariance kernel
+- Running MCMC for a **non-detection** (example1) and deriving a rigorous 3-σ upper limit
+- Running MCMC for a clear **detection** (example2) and extracting flux posteriors
+- Diagnosing convergence via chain traces and autocorrelation times
+- Producing publication-quality corner plots and residual triptychs
+
+---
+
+## Module Overview
+
+| Module | Contents |
+|--------|----------|
+| `jwst_psfmc.psf` | PSF shifting, downsampling, model evaluation |
+| `jwst_psfmc.covariance` | Covariance kernel estimation, Fourier-space pre-computation |
+| `jwst_psfmc.mcmc` | MCMC preparation, log-prob, `run_mcmc`, posterior summaries |
+| `jwst_psfmc.io` | Save/load `.npz` results |
+| `jwst_psfmc.plot` | Triptych, chain traces, corner plot |
+
+---
+
+## Citation
+
+If you use `jwst_psfmc` in your research, please cite:
+
+> Zhuang et al. (in prep.), *NEXUS JWST Transient Survey Year 1*
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

jwst_psfmc-0.1.0/jwst_psfmc/__init__.py

@@ -0,0 +1,104 @@
+"""
+jwst_psfmc
+==========
+
+PSF photometry with MCMC for JWST (and HST) drizzled difference images.
+
+Accounts for correlated pixel noise introduced by the drizzle algorithm via
+a Fourier-space covariance likelihood. The four fitted parameters are:
+
+    flux   – total source flux in the same units as the image
+    dx     – sub-pixel x-shift of the PSF centre (native pixels)
+    dy     – sub-pixel y-shift of the PSF centre (native pixels)
+    bkg    – flat residual background
+
+Public API
+----------
+PSF manipulation
+    shift_psf_fourier, downsample_psf, prepare_psf_for_oversamp,
+    psf_model, match_shape_center, inspect_psf_shift
+
+Covariance estimation
+    estimate_cov_kernel, prepare_covariance_terms,
+    SplitCosineBellWindow, get_source_mask, find_zero_squares
+
+MCMC fitting
+    prepare_for_fitting, run_mcmc,
+    log_prior, log_likelihood_cov_prepared, log_prob_prepared,
+    summarize_emcee, summarize_flux_from_chain
+
+I/O
+    save_emcee_results, load_emcee_results
+
+Visualisation
+    plot_psf_fit_triptych, plot_chains, plot_corner
+"""
+
+__version__ = "0.1.0"
+
+from .psf import (
+    shift_psf_fourier,
+    downsample_psf,
+    match_shape_center,
+    prepare_psf_for_oversamp,
+    psf_model,
+    inspect_psf_shift,
+)
+from .covariance import (
+    SplitCosineBellWindow,
+    distance_grid,
+    estimate_cov_kernel,
+    prepare_covariance_terms,
+    get_source_mask,
+    find_zero_squares,
+)
+from .mcmc import (
+    log_prior,
+    log_likelihood_cov_prepared,
+    log_prob_prepared,
+    prepare_for_fitting,
+    run_mcmc,
+    summarize_emcee,
+    summarize_flux_from_chain,
+)
+from .io import (
+    save_emcee_results,
+    load_emcee_results,
+)
+from .plot import (
+    plot_psf_fit_triptych,
+    plot_chains,
+    plot_corner,
+)
+
+__all__ = [
+    # psf
+    "shift_psf_fourier",
+    "downsample_psf",
+    "match_shape_center",
+    "prepare_psf_for_oversamp",
+    "psf_model",
+    "inspect_psf_shift",
+    # covariance
+    "SplitCosineBellWindow",
+    "distance_grid",
+    "estimate_cov_kernel",
+    "prepare_covariance_terms",
+    "get_source_mask",
+    "find_zero_squares",
+    # mcmc
+    "log_prior",
+    "log_likelihood_cov_prepared",
+    "log_prob_prepared",
+    "prepare_for_fitting",
+    "run_mcmc",
+    "summarize_emcee",
+    "summarize_flux_from_chain",
+    # io
+    "save_emcee_results",
+    "load_emcee_results",
+    # plot
+    "plot_psf_fit_triptych",
+    "plot_chains",
+    "plot_corner",
+]