Documentation

Complete guide to installing and using RamanLab

Quick Start

Prerequisites

Installation Steps

1. Clone or Download the Repository

git clone https://github.com/aaroncelestian/RamanLab.git cd RamanLab

2. Create a Virtual Environment (Recommended)

It is strongly recommended to create a dedicated virtual environment:

python -m venv ramanlab_env

Activate the environment:

macOS/Linux:

source ramanlab_env/bin/activate

Windows:

ramanlab_env\Scripts\activate
You should see (ramanlab_env) in your terminal prompt when the environment is active.

3. Install Dependencies

pip install -r requirements_qt6.txt

4. Verify Installation (Recommended)

python check_dependencies.py

This will check:

5. Download the Database File (Required)

The main Raman spectra database is not included in the repository due to its size (200MB+).

Download link: https://zenodo.org/records/15742626

Installation locations (choose one):

6. Launch RamanLab

python main_qt6.py

Optional: Install Desktop Icon

For convenient access, install a desktop shortcut/application icon:

python install_desktop_icon.py

This will create:

To uninstall the icon:

python install_desktop_icon.py --uninstall

Basic Usage

Loading a Spectrum

  1. Click File → Import Spectrum or drag-and-drop a file onto the window
  2. Select your data file (.txt or .csv format)
  3. The spectrum will be displayed in the main plot area

Baseline Correction

  1. Go to the Process tab
  2. Select a baseline method (ALS recommended)
  3. Adjust parameters using sliders
  4. Preview updates in real-time
  5. Click Apply to apply the correction

Peak Detection

  1. In the Process tab, go to the Profile subtab
  2. Adjust peak detection parameters (height, distance, prominence)
  3. Click Detect Peaks
  4. Detected peaks will be marked on the spectrum

Peak Fitting

  1. After detecting peaks, click Fit Peaks
  2. Select a peak model (Lorentzian, Gaussian, Voigt, etc.)
  3. View fit results in the Analysis Results table
  4. Export results to CSV if needed

Database Search

  1. Load your spectrum
  2. Go to the Search tab
  3. Click Search Database
  4. View top matches with correlation scores
  5. Click on a match to overlay it with your data

Saving Results

  1. Click File → Save Spectrum to save processed data
  2. Use Export options to save peak parameters as CSV
  3. Right-click on plots to save images

Advanced Modules

Multi-Spectrum Manager

Launch from the main window: File → Multi-Spectrum Manager

Cluster Analysis

python raman_cluster_analysis_qt6.py

2D Map Analysis

python map_analysis_2d_qt6.py

Database Browser

python database_browser_qt6.py

Polarization Analyzer

python raman_polarization_analyzer_qt6.py

File Formats

Supported Import Formats

Expected Data Format

# Optional header lines (start with #) Wavenumber Intensity 100.0 1234.5 101.0 1245.8 ...

Export Formats

Troubleshooting

Dependency Check Failures

Problem: check_dependencies.py reports missing or outdated packages

Solution:

  1. Ensure virtual environment is activated (if you created one)
  2. Install all requirements: pip install -r requirements_qt6.txt
  3. Upgrade outdated packages: pip install --upgrade <package-name>
  4. Check Python version: python --version (should be 3.8 or higher)

"Database Not Found" Warning

Problem: Application starts with empty database (0 spectra)

Solution:

  1. Download RamanLab_Database_20250602.pkl from Zenodo
  2. Place in Documents/RamanLab_PySide6/ folder
  3. Restart RamanLab

Import Errors

Problem: Cannot import database files

Solution:

Performance Issues

Problem: Slow processing on large datasets

Solutions:

Window Too Large for Screen

Problem: Application window doesn't fit on laptop screens

Solution:

System Requirements

Hardware

Software

Key Dependencies

Need More Help?

Join our community or watch video tutorials for assistance

Support Forum YouTube Tutorials