# 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.

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Documentation Status](https://readthedocs.org/projects/guibrushr/badge/?version=latest)](https://guibrushr.readthedocs.io/en/latest/?badge=latest)
[![PyPI version](https://img.shields.io/pypi/v/guibrushr.svg)](https://pypi.org/project/guibrushr/)
[![Paper](https://img.shields.io/badge/Paper-ADS-red.svg)]()

---

## 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](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)
- [Support](#support)
- [License](#license)
- [Citation](#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](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html).

#### 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**
```bash
conda config --add channels conda-forge
```

**Step 2: Set Channel Priority**
```bash
conda config --set channel_priority strict
```

**Step 3: Remove Default Channels**
```bash
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:
```bash
nano ~/.condarc
```

Ensure the file contains the following:
```yaml
channels:
  - conda-forge
channel_priority: strict
```

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

**Verification**

To confirm your configuration, run:
```bash
conda config --show channels
```

You should see only `conda-forge` listed.

### 2. Install gfortran

**macOS:**
```bash
brew install gcc
```

**Linux:**
```bash
sudo apt install gfortran
```

### 3. Install Git

**macOS:**
```bash
brew install git
```

**Linux:**
```bash
sudo apt install git
```

---

## Installation

> **Important:** To access the GUIBRUSHR project, please email [paolo.giacobbe@inaf.it](mailto:paolo.giacobbe@inaf.it) or [francesco.amadori@inaf.it](mailto:francesco.amadori@inaf.it) 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)**
```bash
pip install guibrushr==1.0.5
```

**Option B: Clone the Repository**
```bash
mkdir -p /preferred/path/guibrushr
cd /preferred/path/guibrushr/
git clone https://www.ict.inaf.it/gitlab/guibrushr/guibrushr
```

### Step 2: Create Conda Environment

```bash
conda create -n guibrushr_env python=3.10
```

If the command above fails, try:
```bash
conda create -n guibrushr_env python=3.10 --override-channels -c conda-forge
```

### Step 3: Activate the Environment

```bash
conda activate guibrushr_env
```

### Step 4: Install GUIBRUSHR

Navigate to the GUIBRUSHR folder and install in development mode:
```bash
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](https://petitradtrans.readthedocs.io/en/latest/content/notebooks/getting_started.html)
- [High-Resolution Spectra Tutorial](https://petitradtrans.readthedocs.io/en/latest/content/notebooks/high_resolution_spectra.html)

#### 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**
```bash
nano ~/.petitradtrans/petitradtrans_config_file.ini
```

**Step 2: Update the Paths**

The default configuration will look like this:
```ini
[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:
```ini
[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
```bash
cd /preferred/path/guibrushr/GUIBRUSHR/GUIBRUSHR/Files/Configuration_Path/
```

#### Step 2: Create `configuration.csv`

Create a file named `configuration.csv` with the following structure:
```csv
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:
```csv
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:
```bash
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:
```bash
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:
```bash
# 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:
```bash
conda activate guibrushr_env
```

### Launch GUIBRUSHR

Navigate to the GUIBRUSHR directory and start the application:
```bash
cd /preferred/path/guibrushr/GUIBRUSHR
python Start_GUIBRUSHR.py
```

---

## Troubleshooting

### Common Issues

**Environment activation error:**
```bash
# Make sure you created the environment with the correct name
conda env list
```

**Import errors after installation:**
```bash
# 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**  
📧 [francesco.amadori.97.astro@gmail.com](mailto:francesco.amadori.97.astro@gmail.com)  
📧 [francesco.amadori@inaf.it](mailto:francesco.amadori@inaf.it)

**Paolo Giacobbe**  
📧 [paolo.giacobbe@inaf.it](mailto: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](https://petitradtrans.readthedocs.io/) - Radiative transfer calculations
- [conda-forge](https://conda-forge.org/) - Community-driven package repository

---

*Last updated: October 2025*