GUIBRUSHR

Graphical User Interface for Bayesian Retrievals Using Spectroscopy at High Resolution

A powerful tool for performing Bayesian atmospheric retrievals and cross-correlations on high- and low-resolution spectroscopic data of exoplanets.

---

Overview

GUIBRUSHR provides an intuitive interface for analyzing exoplanetary atmospheres through:

• Bayesian atmospheric retrieval - Determine atmospheric composition and properties
• High and low-resolution spectroscopy support - Work with various data types
• Cross-correlation analysis - Detect molecular signatures
• petitRADTRANS integration - Leverage state-of-the-art radiative transfer

---

Table of Contents

• Prerequisites
• Installation
• Utility Commands
• Configuration
• Usage
• Troubleshooting
• Support
• License
• Citation

---

Prerequisites

Before installing GUIBRUSHR, ensure you have the following installed on your system:

1. Install Conda

If you don't already have Conda installed, download it from conda.io.

Removing Anaconda Default Channels

To avoid potential licensing fees associated with Anaconda's default package channels, configure Conda to use the community-maintained conda-forge channel instead.

Step 1: Add conda-forge Channel

conda config --add channels conda-forge

Step 2: Set Channel Priority

conda config --set channel_priority strict

Step 3: Remove Default Channels

conda config --remove channels defaults

Note: If the command above returns an error, manually edit the configuration file instead.

Manual Configuration (if needed)

If Step 3 fails, edit the .condarc file directly:

nano ~/.condarc

Ensure the file contains the following:

channels:
  - conda-forge
channel_priority: strict

Save and exit (Ctrl+O, then Ctrl+X).

Verification

To confirm your configuration, run:

conda config --show channels

You should see only conda-forge listed.

2. Install gfortran

macOS:

brew install gcc

Linux:

sudo apt install gfortran

3. Install Git

macOS:

brew install git

Linux:

sudo apt install git

---

Installation

Important: To access the GUIBRUSHR project, please email paolo.giacobbe@inaf.it or francesco.amadori@inaf.it to request an invitation to the GitLab group.

Step 1: Create Conda Environment

conda create -n guibrushr_env python=3.10
conda activate guibrushr_env

If the command above fails, try:

conda create -n guibrushr_env python=3.10 --override-channels -c conda-forge
conda activate guibrushr_env

Step 2: Install GUIBRUSHR

Option A: Install from PyPI

pip install guibrushr

Option B: Clone and install in GitLab mode (more tested)

mkdir -p /preferred/path/guibrushr
cd /preferred/path/guibrushr/
git clone https://www.ict.inaf.it/gitlab/guibrushr/guibrushr
cd GUIBRUSHR
pip install -e ."

Step 3: Download GUIBRUSHR Data Files (mainly necessary if installed via PyPI)

After installation, download the required data files (YAML configs, grids, molecular data, ~160 MB):

guibrushr-download

Step 4: Configure GUIBRUSHR

Create or edit the configuration file specifying your petitRADTRANS and target folder paths:

guibrushr-config

If the file does not exist, the command will guide you through creating it interactively by asking for the two required paths.

Step 5 (Optional): Download Tutorial/Test Dataset

To get started quickly with a ready-to-use example, download the WASP-77Ab dataset (~200 MB) and the required petitRADTRANS opacity files (~8 GB compressed, ~9 GB on disk):

⚠️ Complete Step 4 before running this command — it requires valid paths in configuration.csv.

guibrushr-tutorial-download

This will:

• Extract the WASP-77Ab target dataset into your configured target folder
• Add missing petitRADTRANS opacity files without overwriting existing ones

---

Utility Commands

After installation, the following commands are available from any terminal (with the conda environment active):

Command	Description
guibrushr	Launch the main application
guibrushr-help	List every available command with a short description
guibrushr-download	Download GUIBRUSHR core data files (~160 MB)
guibrushr-tutorial-download	Download test dataset (WASP-77Ab + petitRADTRANS opacities)
guibrushr-config	Create or edit configuration.csv interactively
guibrushr-yaml	Interactively select and edit YAML configuration files with nano
guibrushr-db	View and manage the GUIBRUSHR SQLite database
guibrushr-git-config	Mark the configuration YAML files skip-worktree after a git clone
guibrushr-backup-yaml	Save timestamped copies of the configuration YAML files
guibrushr-check-yaml-online	Check whether the configuration YAML files changed upstream
guibrushr-inspect-checkpoint	Inspect an MCMC checkpoint offline (frozen or stuck chains)

---

Configuration

Part 1: Setting up petitRADTRANS

GUIBRUSHR requires petitRADTRANS to be properly configured. Follow these official tutorials to set up the input_data folder and download molecular data at both high and low resolution:

• Getting Started with petitRADTRANS
• High-Resolution Spectra Tutorial

Pre-flight Checklist

Before running GUIBRUSHR, ensure you have completed the following:

• ✅ Defined the location of your petitRADTRANS input_data folder
• ✅ Downloaded at least one molecule of interest at both high and low resolution
• ✅ Defined the location of your target folder

Configure petitRADTRANS Paths

IMPORTANT: After installing petitRADTRANS, you must configure the data paths.

Step 1: Open the Configuration File

nano ~/.petitradtrans/petitradtrans_config_file.ini

Step 2: Update the Paths

The default configuration will look like this:

[Default files]

[Paths]

prt_input_data_path = /home/<username>/petitRADTRANS/input_data
prt_outputs_path = /home/<username>/petitRADTRANS/outputs

[URLs]

prt_input_data_url = https://keeper.mpdl.mpg.de/d/ccf25082fda448c8a0d0/?p=

Replace the default paths with your actual petitRADTRANS installation directory:

[Default files]

[Paths]

prt_input_data_path = /pRT/preferred/path/petitRADTRANS/input_data
prt_outputs_path = /pRT/preferred/path/petitRADTRANS/outputs

[URLs]

prt_input_data_url = https://keeper.mpdl.mpg.de/d/ccf25082fda448c8a0d0/?p=

Step 3: Save and Exit — Press Ctrl+O to save, then Ctrl+X to exit nano.

Part 2: GUIBRUSHR Configuration File

The easiest way to create the configuration file is via the dedicated command:

guibrushr-config

This will show you the exact path of the file and guide you interactively. Alternatively, create it manually at:

<site-packages>/GUIBRUSHR/Files/Configuration_Path/configuration.csv

With this structure:

Element,Path
petitRadTrans_path,/pRT/preferred/path/petitRADTRANS/input_data/
path_target_folders,/target/preferred/path/

Example:

Element,Path
petitRadTrans_path,/home/francesco/petitRADTRANS/input_data/
path_target_folders,/home/francesco/Target_GUIBRUSHR/

Field	Description
petitRadTrans_path	Absolute path to your petitRADTRANS input_data folder
path_target_folders	Absolute path to your GUIBRUSHR target data folder

Tip: Always use absolute paths to avoid potential path resolution issues.

Part 3: Editing YAML Configuration Files

GUIBRUSHR uses several YAML files to configure molecules, parameters, graphics and more. To edit them interactively:

guibrushr-yaml

This will show a numbered menu of all available YAML files and open the selected one with nano. The available configuration files are:

File	Description
condensed.yaml	Condensed chemistry settings
general.yaml	General application settings
graphics.yaml	GUI layout and appearance settings
hybrid_elements.yaml	Hybrid chemistry element settings
molecules.yaml	Molecular species configuration
parameters.yaml	Retrieval parameter settings

Part 4: Git Configuration for Local Modifications

If you installed via git clone, prevent accidental conflict of your local molecules.yaml:

git update-index --assume-unchanged GUIBRUSHR/Files/Configuration_Yaml/molecules.yaml

To pull remote updates to this file when needed:

git update-index --no-assume-unchanged GUIBRUSHR/Files/Configuration_Yaml/molecules.yaml
git pull
git update-index --assume-unchanged GUIBRUSHR/Files/Configuration_Yaml/molecules.yaml

Note: If you have local modifications when pulling, stash them first with git stash, pull, then reapply with git stash pop.

Why This Approach?

Using git update-index --assume-unchanged allows you to:

• ✅ Keep the default configuration in the repository
• ✅ Make local customizations without affecting version control
• ✅ Avoid accidentally committing personal configuration changes
• ✅ Still receive updates to the file from the main repository when needed

---

Usage

Activate the Environment

Before using GUIBRUSHR, always activate the Conda environment:

conda activate guibrushr_env

Launch GUIBRUSHR

Via built-in command

guibrushr

Via standard python command (more tested)

Navigate to the GUIBRUSHR directory and start the application:

cd /preferred/path/guibrushr/GUIBRUSHR
python Start_GUIBRUSHR.py

---

Troubleshooting

Common Issues

Environment activation error:

# Make sure you created the environment with the correct name
conda env list

Import errors after installation:

# Reinstall in development mode
pip install -e . --force-reinstall

Configuration file not found:

• Run guibrushr-config to create it interactively
• Verify that paths in the CSV file are absolute and correct

Data files missing after installation:

# Re-run the data downloader manually
guibrushr-download

petitRADTRANS not found:

• Ensure petitRADTRANS is properly installed and configured
• Verify the path in ~/.petitradtrans/petitradtrans_config_file.ini is correct
• Check that molecular data has been downloaded
• Run guibrushr-tutorial-download to download the test opacity dataset

Permission denied errors:

• Ensure you have write permissions for the output directories
• Check that all paths in configuration.csv are accessible

Database issues:

# Inspect and manage the database interactively
guibrushr-db

---

Support

For questions, bug reports, or technical assistance, please contact:

Francesco Amadori 📧 francesco.amadori.97.astro@gmail.com 📧 francesco.amadori@inaf.it

Paolo Giacobbe 📧 paolo.giacobbe@inaf.it

---

License

GUIBRUSHR is 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, either version 3 of the License, or (at your option) any later version.

This program 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.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

---

Citation

If you use GUIBRUSHR in your research, please cite:

[Paper submitted and in reviewing by JOSS]

---

Acknowledgments

GUIBRUSHR relies on the following open-source projects:

• petitRADTRANS - Radiative transfer calculations
• conda-forge - Community-driven package repository

This work is supported by the Fondazione ICSC, Spoke 3 Astrophysics and Cosmos Observations, National Recovery and Resilience Plan (Piano Nazionale di Ripresa e Resilienza, PNRR) Project ID CN 00000013 "Italian Research Center on High-Performance Computing, Big Data, and Quantum Computing" funded by MUR Missione 4 Componente 2 Investimento 1.4: Potenziamento strutture di ricerca e creazione di "campioni nazionali di R&S (M4C2-19)" - Next Generation EU (NGEU).

The authors acknowledge financial contribution from the European Union - Next Generation EU RRF M4C2 1.1 PRIN MUR 2022 project 2022CERJ49 (ESPLORA).

---

Last updated: March 2026