Welcome to GUIBRUSHR's Documentation! ====================================== .. image:: ../../GUIBRUSHR/Files/logo.png :width: 300px :align: center :alt: GUIBRUSHR Logo | .. image:: https://img.shields.io/badge/License-GPLv3-blue.svg :target: https://www.gnu.org/licenses/gpl-3.0 :alt: License: GPL v3 .. image:: https://readthedocs.org/projects/guibrushr/badge/?version=latest :target: https://guibrushr.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. image:: https://img.shields.io/pypi/v/guibrushr.svg :target: https://pypi.org/project/guibrushr/ :alt: PyPI version .. image:: https://img.shields.io/badge/Paper-ADS-red.svg :target: # :alt: Paper | **GUIBRUSHR** (Graphic User Interface for Bayesian Retrieval Using Spectroscopy at High Resolution) is a comprehensive Python tool designed to perform end-to-end atmospheric characterization of exoplanets, from spectral processing to Bayesian retrieval, supporting both high-resolution (HR) and low-resolution (LR) datasets in a multi-instrument framework. The observation of exoplanetary atmospheres contains crucial information about planet formation, evolution, and potential habitability. Ground-based HR spectroscopy (R > 25,000) with échelle spectrographs such as GIANO-B, IGRINS, CRIRES+, CARMENES, and NIRPS, and space-based LR spectrophotometry with JWST and HST, provide complementary information thanks to their sensitivity to different atmospheric depths. GUIBRUSHR aims to unify the different steps of atmospheric characterization --- from reduced spectra to atmospheric retrievals, including telluric line removal and cross-correlation function (CCF) analysis --- into a single, well-documented graphical interface backed by an integrated database. Key Features ------------ **Graphical Interface and Data Management** * Graphical interface built on tkinter, allowing users to operate without dealing with multiple configuration files. * All data related to the retrieval process are stored in a local SQLite3 database: folders, records, files, results, and internal configurations are organized so that users can easily visualize and interact with them through the interface. * Compatible with Python 3.10 and above. **Multi-Resolution and Multi-Instrument Support** * Analysis and manipulation of datasets at both high resolution (HR, R > 25,000) and low resolution (LR, R < 4,000), either separately or in combination. * Multi-instrument approach: users can integrate datasets from different instruments for both CCF analyses and retrieval procedures. * Support for transmission and emission spectroscopy. **Radiative Transfer** * Uses petitRADTRANS v3.0 as the primary radiative transfer engine. * HR opacities natively provided at R = 10\ :sup:`6`, with a configurable line-by-line sampling factor. * LR opacities available in both correlated-k and line-by-line modes. * Ongoing implementation of PyratBay in a GPU framework. **Bayesian Retrieval** * Self-developed, parallelized Python implementation of the EXOFAST fitting algorithm, based on the Differential Evolution Markov Chain Monte Carlo (DE-MCMC) technique. * Configurable number of chains per parameter and CPU cores. * Dedicated likelihood functions for HR, LR, and combined HR+LR retrievals. **Telluric Removal** * PCA-based removal of telluric and stellar contamination from HR datasets. * Multi-step masking procedure (throughput correction, low-sensitivity channels, telluric/stellar contamination, phase-dependent variability) with user-adjustable thresholds via the GUI. * Extensible architecture supporting future user-defined custom functions as plugins. **Cross-Correlation Analysis** * CCF analysis for detecting molecular species in HR spectroscopy datasets. * Support for combining multiple nights from a single instrument or across different instruments to increase the SNR. * Masking of specific orbital phase or radial velocity ranges to exclude contaminated regions. **Forward Modeling and Synthetic Observations** * Generation of atmospheric models by manually adjusting parameter configurations (planetary properties, cloud/haze opacities, temperature--pressure profiles, chemical composition). * Generation of synthetic HR observations incorporating telluric absorption, stellar spectra via the PHOENIX archive, and photon noise. Main Modules ------------ GUIBRUSHR is organized into several main modules, each accessible through a dedicated tab panel in the graphical interface: * **General Configuration** -- Initial setup of the analysis environment: paths to target folders, instrument data, and opacity databases. * **Run Retrievals** -- Configuration of all parameters necessary to model 1D atmospheres, including the pressure--temperature profile and cloud parameterization. * **Retrieval Analysis and Cross-Correlation** -- Core analysis module for visualizing posterior distributions, best-fit models, performing CCF on retrieved models, and managing retrieval runs. * **Telluric Removal** -- Dedicated module for removing Earth's atmospheric features from HR spectra using PCA-based algorithms with configurable masking options. * **Forward Model** -- Interactive generation of atmospheric models for exploring parameter space and building model libraries for CCF analyses. * **Cross-Correlation Night-Forward** -- CCF analysis using forward models, with multi-night and multi-instrument combination capabilities. * **Generation HR Datasets** -- Generation of synthetic HR observations with realistic telluric, stellar, and noise components. * **DB and Data Interactions** -- Interface to the SQLite3 database for managing instrument configurations, observatory information, target properties, and retrieval records. .. toctree:: :maxdepth: 2 :caption: Getting Started installation .. toctree:: :maxdepth: 2 :caption: Tutorial tutorial/index .. toctree:: :maxdepth: 2 :caption: API Reference modules Citation -------- If you use GUIBRUSHR in your research, please cite: .. note:: Amadori, Giacobbe et al. -- *GUIBRUSHR: A comprehensive tool to characterize exoplanet atmospheres at different spectroscopic resolutions and with a multi-instrument approach* (submitted to the Open Journal of Astrophysics). License ------- GUIBRUSHR is free software distributed under the GNU General Public License v3.0. You can redistribute it and/or modify it under the terms of the license as published by the Free Software Foundation, either version 3, or (at your option) any later version. See `GNU GPL v3.0 `_ for details. Authors & Contact ----------------- **Main Developer and Co-Creator:** * **Francesco Amadori** -- francesco.amadori@inaf.it / francesco.amadori.97.astro@gmail.com **Creator of the Project:** * **Paolo Giacobbe** -- paolo.giacobbe@inaf.it For questions, bug reports, or technical assistance, please use the `GitLab repository `_ or contact the authors at the addresses above. Acknowledgments --------------- This work is supported by Fondazione ICSC, Spoke 3 Astrophysics and Cosmos Observations (PNRR Project ID CN 00000013), and by the European Union -- Next Generation EU (PRIN MUR 2022 project 2022CERJ49, ESPLORA). GUIBRUSHR relies on several open-source packages, including: * `petitRADTRANS `_ -- Radiative transfer * `PyratBay `_ -- Atmospheric modeling and spectral binning * `NumPy `_, `SciPy `_, `Matplotlib `_ -- Scientific computing and visualization * `Astropy `_ -- Astronomy utilities * `barycorrpy `_ -- Barycentric corrections * `pandas `_ -- Data structures * `tkinter `_ -- GUI framework Indices and Tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`