timothygebhard / hsr4hci

Half-Sibling Regression for High-Contrast Imaging

Half-Sibling Regression for High-Contrast Imaging

---

This repository contains the code for all experiments and figures in our paper:

Gebhard, T. D., Bonse, M. J., Quanz, S. P., & Schölkopf, B. (2022). Half-sibling regression meets exoplanet imaging: PSF modeling and subtraction using a flexible, domain knowledge-driven, causal framework. Astronomy & Astrophysics, 666, A9. Also available on arXiv:2204.03439.

---

📚 Documentation

A full documentation of the entire code base, including descriptions of the different scripts and step-by-step guides for (re)-running our experiments can be found on ReadTheDocs.

⚡ Getting started

The code in this repository is organized as a Python package named hsr4hci together with a set of scripts that use the functions and classes of the package. To get started, clone this repository and install hsr4hci as a Python package:

git clone [e-mail]:timothygebhard/hsr4hci.git
cd hsr4hci
pip install -e .

The -e option installs the package in "edit mode", which ensures that runs directly from the folder that you got by cloning this repository, instead of being copied to the site-package of your Python installation (a location where you usually would not want to store, e.g., data set files).

If you want to use "developer options" (e.g., run unit tests), change the last line to:

pip install -e ".[develop]"

Note: The code was written for Python 3.8 and above; earlier versions will likely require some small modifications.

🐭 Tests

This repository comes with an extensive set of unit and integration tests (based on pytest). After installing hsr4hci with the [develop] option, the tests can be run as:

pytest tests

You can also use these tests to ensure that the code is compatible with newer versions of the libraries than the one in setup.py.

🪐 Data sets

To run any experiments or reproduce our results, you will first need to download or create some data sets in the right format. Please check out the documentation for more detailed information on how to do this.

🧪 (Re)-running our experiments

All of our experiments can be found in the experiments directory. The documentation (see below) contains detailed instructions for how to (re)-run them. A good starting point if you are just getting started could the to run the demo experiment that we have prepared in the demo directory.

📜 Citing this work

To cite this work, please feel free to use the following BibTeX entry:

@article{Gebhard_2022,
  title         = {{Half-sibling regression meets exoplanet imaging: PSF modeling and subtraction using a flexible, domain knowledge-driven, causal framework}},
  author        = {Timothy D. Gebhard and Markus J. Bonse and Sascha P. Quanz and Bernhard Schölkopf},
  year          = 2022,
  month         = 9,
  doi           = {10.1051/0004-6361/202142529},
  publisher     = {{EDP} Sciences},
  volume        = 666,
  pages         = {A9},
  journal       = {Astronomy \& Astrophysics},
}

✏️ Authors

All code was written by Timothy Gebhard, with additional contributions from Markus Bonse.

⚖️ License and copyright

The code in this repository is property of the Max Planck Society.

We are releasing it under a BSD-3 Clause License; see LICENSE for more details.