STARRED: STARlet REgularized Deconvolution

STARlet REgularized Deconvolution (STARRED) is a Python deconvolution method powered by Starlet regularization and JAX automatic differentiation. It uses a Point Spread Function (PSF) narrower than the original one as kernel.

The main Documentation can be found here

Installation

Through PyPI

STARRED releases are distributed through the Python Package Index (PyPI). To install the latest version use pip:

$ pip install starred-astro

or, with the optional dependencies:

$ pip install starred-astro[opt]

The correlated field background model relies on NIFTy, which is installed through the dedicated cf extra:

$ pip install starred-astro[cf]

You can also combine extras, e.g. pip install starred-astro[opt,cf].

Through Anaconda

We provide an Anaconda environment that satisfies all the dependencies in starred-env.yml.

$ git clone https://gitlab.com/cosmograil/starred.git
$ cd starred
$ conda env create -f starred-env.yml
$ conda activate starred-env
$ pip install .

In case you have an NVIDIA GPU, this should automatically download the right version of JAX as well as cuDNN. Next, you can run the tests to make sure your installation is working correctly.

# While still in the STARRED directory:
$ pytest . 

Manually handling the dependencies

If you want to use an existing environment, just omit the Anaconda commands above:

$ git clone https://gitlab.com/cosmograil/starred
$ cd starred 
$ pip install .

or if you need to install it for your user only:

$ python setup.py install --user 

STARRED runs much faster on GPUs, so make sure you install a version of JAX that is compatible with your version of CUDA and cuDNN. Refer to the installation page of the JAX documentation.

Requirements

STARRED requires the following Python packages:

• astropy
• dill
• jax
• jaxlib
• matplotlib
• numpy
• scipy
• optax
• tqdm
• h5py

Additionnaly, the following package needs to be installed if you want to sample posterior distribution:

• emcee
• mclmc

Other optional dependencies are required for specific functionalities:

• scikit-image for the reconstruction of the narrow PSF from a PSF model.
• pyregion for the reading of DS9 region files.
• nifty (installed via the cf extra) for the correlated field background model, which parameterizes the deconvolution background as a Gaussian process instead of starlet-regularized free pixels.

Graphical interface

A desktop application, the STARRED PSF Reconstructor, provides a point-and-click front-end to the JWST PSF reconstruction workflow: FITS import, star detection and filtering, interactive candidate selection with per-star masking, and inspection of the reconstructed PSF, residuals and error map.

It is installed with the gui extra and launched with the starred-gui command:

$ pip install "starred-astro[gui]"
$ starred-gui

The gui extra only adds photutils (source detection) and Pillow (thumbnail rendering); everything else the application needs is already a core STARRED dependency, so a plain pip install starred-astro is unchanged. tkinter is part of the standard library but is packaged separately by some distributions — the application tells you how to install it if it is missing.

See the GUI README for the full workflow description and details.

Example Notebooks and Documentation

We provide several notebooks to help you get started.

Start here to grasp the basic STARRED workflow.

More example notebooks going in more detail of how the internals work can be found in the notebooks directory:

• Ground-based narrow PSF generation
• Ground-based joint deconvolution
• Another ground-based joint deconvolution
• JWST PSF generation and deconvolution
• JWST deconvolution with a correlated field background
• DES2038 joint deconvolution
• HST PSF reconstruction
• JWST PSF reconstruction

The mathematical formalism along with further examples are also presented in Millon et al. (2024). All the examples and tests presented in this paper can be reproduced from this repository:

• STARRED Examples

You can also run STARRED from the command line by following these instructions. STARRED is now fully integrated into lightcurver,
which helps you producing light curves by preparing your data in the correct format to be analyzed by STARRED and ensure accurate epoch-to-epoch photometric calibration.

Finally, the full documentation can be found here and a video presentation of STARRED is accessible on Youtube.

STARRED users community

If you want to join the STARRED users community on Slack to ask questions, propose future developments or share your latest results, please send an email to this address to get an invitation link.

Attribution

If you use this code, please cite Michalewicz et al. 2023 and Millon et al. 2024 as indicated in the documentation.

License

STARRED is a free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation.

STARRED is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY, without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details (LICENSE.txt).