Metadata-Version: 2.4
Name: guibrushr
Version: 1.0.9
Summary: GUIBRUSHR: GUI for Bayesian Retrieval Using Spectroscopy at High Resolution.
Author-email: Francesco Amadori <francesco.amadori.97.astro@gmail.com>, Francesco Amadori <francesco.amadori@inaf.it>, Paolo Giacobbe <paolo.giacobbe@inaf.it>
Project-URL: Homepage, https://www.ict.inaf.it/gitlab/guibrushr/guibrushr
Project-URL: Issues, https://www.ict.inaf.it/gitlab/guibrushr/guibrushr/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: astroquery
Requires-Dist: astropy>=6.0
Requires-Dist: barycorrpy
Requires-Dist: celerite
Requires-Dist: ccdproc
Requires-Dist: chemcat
Requires-Dist: docopt
Requires-Dist: drslib
Requires-Dist: exo-k
Requires-Dist: furo
Requires-Dist: gdown
Requires-Dist: matplotlib>=3.9
Requires-Dist: mc3
Requires-Dist: meson-python
Requires-Dist: mpi4py
Requires-Dist: ninja
Requires-Dist: numpy>=2.0
Requires-Dist: openmpi
Requires-Dist: pandas
Requires-Dist: petitRADTRANS
Requires-Dist: pillow
Requires-Dist: psycopg2-binary
Requires-Dist: pyastronomy
Requires-Dist: pygtc
Requires-Dist: pydl
Requires-Dist: pypl
Requires-Dist: pyreadstat
Requires-Dist: pyratbay>=2.0
Requires-Dist: pysal
Requires-Dist: requests
Requires-Dist: requests-cache
Requires-Dist: seaborn
Requires-Dist: scipy>=1.13
Requires-Dist: screeninfo
Requires-Dist: setuptools
Requires-Dist: skycalc_cli
Requires-Dist: sphinx
Requires-Dist: sphinx_rtd_theme
Requires-Dist: sphinx_book_theme
Requires-Dist: tk
Requires-Dist: tkPDFViewer
Requires-Dist: watchdog
Provides-Extra: upgrade
Requires-Dist: astropy>=6.0; extra == "upgrade"
Requires-Dist: chemcat; extra == "upgrade"
Requires-Dist: numpy>=2.0; extra == "upgrade"
Requires-Dist: scipy>=1.13; extra == "upgrade"
Requires-Dist: matplotlib>=3.9; extra == "upgrade"
Requires-Dist: pyratbay>=2.0; extra == "upgrade"
Dynamic: license-file

# 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)
- [Utility Commands](#utility-commands)
- [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: Create Conda Environment

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

If the command above fails, try:

```bash
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**

```bash
pip install guibrushr
```

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

```bash
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):

```bash
guibrushr-download
```

### Step 4: Configure GUIBRUSHR

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

```bash
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 (~12 GB):

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

```bash
guibrushr-download-data
```

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-download` | Download GUIBRUSHR core data files (~160 MB) |
| `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-download-data` | Download test dataset (WASP-77Ab + petitRADTRANS opacities) |


***

## 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](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=
```

**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:

```bash
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:

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

**Example:**

```csv
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:

```bash
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`:

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

To pull remote updates to this file when needed:

```bash
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:

```bash
conda activate guibrushr_env
```


### Launch GUIBRUSHR

#### Via built-in command
```bash
guibrushr
```

#### Via standard python command (more tested)
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:**

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

**Data files missing after installation:**

```bash
# 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-download-data` 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:**

```bash
# 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](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/](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


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*
