guibrushr 1.0.5

GUIBRUSHR: GUI for Bayesian Retrieval Using Spectroscopy at High Resolution.

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
• 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 [e-mail] or [e-mail] to request an invitation to the GitLab group.

Step 1: Get GUIBRUSHR

Choose one of the following installation methods:

Option A: Install from PyPI (recommended)

pip install guibrushr==1.0.5

Option B: Clone the Repository

mkdir -p /preferred/path/guibrushr
cd /preferred/path/guibrushr/
git clone https://www.ict.inaf.it/gitlab/guibrushr/guibrushr

Step 2: Create Conda Environment

conda create -n guibrushr_env python=3.10

If the command above fails, try:

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

Step 3: Activate the Environment

conda activate guibrushr_env

Step 4: Install GUIBRUSHR

Navigate to the GUIBRUSHR folder and install in development mode:

cd /preferred/path/guibrushr/GUIBRUSHR
pip install -e .
pip install --upgrade "guibrushr[upgrade]"

---

Configuration

GUIBRUSHR requires two configuration steps: setting up petitRADTRANS and creating the GUIBRUSHR configuration file.

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=

Replace /pRT/preferred/path/petitRADTRANS with the absolute path to your petitRADTRANS installation.

Step 3: Save and Exit

Press Ctrl+O to save, then Ctrl+X to exit nano.

Part 2: Creating the GUIBRUSHR Configuration File

Step 1: Navigate to Configuration Directory

cd /preferred/path/guibrushr/GUIBRUSHR/GUIBRUSHR/Files/Configuration_Path/

Step 2: Create configuration.csv

Create a file named configuration.csv with the following structure:

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

Configuration Example

Here's a complete example of the configuration.csv file:

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

Field Descriptions:

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: Git Configuration for Local Modifications

The molecules.yaml configuration file is tracked in the repository but is meant to be customized locally. To prevent Git from tracking your local changes to this file:

Step 1: Tell Git to Ignore Local Changes

After cloning the repository, run:

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

This tells Git to ignore any local modifications you make to molecules.yaml, so your custom molecule configurations won't appear in git status or be accidentally committed.

Step 2: Verify the Configuration

To check which files are marked as assume-unchanged:

git ls-files -v | grep '^h'

Files marked with h (instead of H) are being ignored for local changes.

Managing Updates from Remote

If the molecules.yaml file is updated in the remote repository and you want to pull those changes:

# Temporarily remove the ignore flag
git update-index --no-assume-unchanged GUIBRUSHR/GUIBRUSHR/Files/Configuration_Yaml/molecules.yaml

# Pull the latest changes
git pull

# Reapply the ignore flag
git update-index --assume-unchanged GUIBRUSHR/GUIBRUSHR/Files/Configuration_Yaml/molecules.yaml

Note: If you have local modifications when pulling remote updates, you may need to stash your changes first with git stash, pull the updates, then reapply your changes with git stash pop.

Why This Approach?

The molecules.yaml file contains default molecular species configurations that should be included when cloning the repository. However, each user may need to add or modify molecules based on their specific research needs. 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

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:

• Verify the configuration.csv file exists in the correct directory
• Check that paths in the CSV file are absolute and correct

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

Permission denied errors:

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

---

Support

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

Francesco Amadori
📧 [e-mail]
📧 [e-mail]

Paolo Giacobbe
📧 [e-mail]

---

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

---

Last updated: October 2025