Author: Aaron J. Celestian, Ph.D.
Curator of Mineral Sciences
Natural History Museum of Los Angeles County
RamanLab is a comprehensive, cross-platform desktop application for analyzing and identifying Raman spectra. Built with PySide6, it provides a modern, professional interface for importing, processing, and matching Raman spectra against databases of known materials with advanced machine learning capabilities and specialized analysis tools.
Current Version: 1.0.3
Release Date: 2025-06-22
Framework: Qt6 (PySide6)
Platform Support: Windows, macOS, Linux
Python Requirements: 3.8+ (3.9+ recommended)
Get RamanLab running in 5 minutes:
# 1. Create and activate conda environment
conda create -n ramanlab python=3.9
conda activate ramanlab
# 2. Clone repository
git clone https://github.com/aaroncelestian/RamanLab.git
cd RamanLab
# 3. Install dependencies
pip install -r requirements_qt6.txt
# 4. Check dependencies (recommended)
python check_dependencies.py
# 5. Launch RamanLab
python launch_ramanlab.py
# 6. Install desktop shortcut (optional)
python install_desktop_icon.pyDownload Essential Databases:
-
Pre-compiled Raman Databases
-
Place these files in the RamanLab directory.
Note: Always use python (not python3) when in the conda environment.
- Multi-Format Import: CSV, TXT, DAT, and other common Raman data formats
- Advanced Background Subtraction: Manual and automated modeling with interactive refinement
- Smart Peak Detection: Algorithmic identification with user override capabilities
- Interactive Visualization: Advanced zooming, panning, and spectral comparison tools
- Publication Quality Exports: High-resolution plots and comprehensive analysis reports
- Comprehensive Storage: Organize Raman spectra with rich metadata and classifications
- Batch Operations: Import multiple spectra with automated processing
- Advanced Search: Multi-criteria filtering with Hey-Celestian classification and element limiting
- Dedicated Database Browser: (
launch_raman_database_browser.py) featuring:- Interactive spectrum visualization with peak analysis
- Comprehensive metadata viewing and editing
- Export capabilities for individual spectra
- Database statistics and classification summaries
- Multiple Algorithms:
- Correlation-based matching
- Peak-based matching (position and intensity)
- Hybrid correlation + peak analysis
- Machine learning-based matching with dynamic time warping
- Advanced Filtering: Peak regions, Hey-Celestian classification, elemental composition
- Confidence Scoring: Statistical assessment of match quality
- Mixed Mineral Analysis: Unique capability to identify multiple minerals in complex spectra
- Molecular Vibrational Groups: Experimental heatmap analysis with chemical scoring
In development by Aaron J. Celestian & RamanLab Development Team
The Hey-Celestian Classification System is a spectroscopy based classification system for mineral specifically designed for Raman spectroscopy. Unlike traditional systems that organize minerals by chemical composition, this system organizes them by their dominant vibrational signatures.
- Framework Modes - Tetrahedral Networks (Quartz, Feldspar, Zeolites)
- Framework Modes - Octahedral Networks (Rutile, Anatase, Spinel)
- Characteristic Vibrational Mode - Carbonate Groups (Calcite, Aragonite)
- Characteristic Vibrational Mode - Sulfate Groups (Gypsum, Anhydrite, Barite)
- Characteristic Vibrational Mode - Phosphate Groups (Apatite, Vivianite)
- Chain Modes - Single Chain Silicates (Pyroxenes, Wollastonite)
- Chain Modes - Double Chain Silicates (Amphiboles, Actinolite)
- Ring Modes - Cyclosilicates (Tourmaline, Beryl, Cordierite)
- Layer Modes - Sheet Silicates (Micas, Clays, Talc, Serpentine)
- Layer Modes - Non-Silicate Layers (Graphite, Molybdenite, Brucite)
- Simple Oxides (Hematite, Magnetite, Corundum)
- Complex Oxides (Spinels, Chromites, Garnets, Perovskites)
- Hydroxides (Goethite, Lepidocrocite, Diaspore)
- Organic Groups (Abelsonite, Organic minerals)
- Mixed Modes (Epidote, Vesuvianite, Complex structures)
These 15 groups will have branching subgroups of a hierarchical, multi-dimensional classification scheme that maintains the elegant simplicity of vibrational mode organization while incorporating the chemical, structural, and environmental complexity that characterizes real mineral systems. This will involve a tree-like structure where the 15 primary vibrational groups serve as main branches, with increasingly specific sub-classifications based on composition, structure, and environmental factors.
- Works with solid solutions
- Polytipic variations
- Polymorph catagories
- Crystal orientation effects
You will notice that a lot of groundwork is already implemented in RamanLab to build out this new classifation system. Once the system is implemented, new quantitaive enhancements could be realized, such as, mixing ratios, crystallinity indices, stress/strain, weathering/alteration pathways, hydration effects, phase diagram integration, metastability, and aid in additive learning systems for future AI predictive modeling.
- Predictive Analysis: Expected peak positions and vibrational characteristics
- Enhanced Database Searching: Filter by vibrational mode families
- Educational Value: Connect structural features to spectral signatures
- Analysis Strategy Guidance: Optimal regions and expected interferences
- Smart Background Models: AI-suggested models with user selection
- Multiple Peak Models: Gaussian, Lorentzian, Pseudo-Voigt, Asymmetric Voigt
- No Region Definition Required: Automatic peak detection across full spectrum
- Reports: Publication-quality graphics with comprehensive fitting statistics
- Unlimited Spectra: Handle large datasets (system memory dependent)
- Automated Background Refinement: Intelligent background modeling across datasets
- Statistical Analysis: 95% confidence intervals (superior to traditional error bars)
- Selective Region Fitting: User-defined regions for optimized processing speed
- Directory-Based Import: Seamless 2D Raman mapping dataset handling
- Multiple Visualization Methods:
- Integrated intensity heatmaps
- Template coefficient visualization
- Component distribution analysis
- Template Analysis:
- Multiple fitting methods (NNLS, LSQ)
- Percentage contribution calculations
- Interactive template visibility controls
- Export template analysis results
- Data Quality Control: Automated cosmic ray filtering
- Machine Learning Integration: PCA, NMF, and Random Forest classification
Specialized module for battery materials research
- Chemical Strain Analysis: Track H/Li exchange effects in battery materials
- Jahn-Teller Distortion Monitoring: Quantify Mn³⁺ formation and structural distortions
- Time Series Processing: Handle time-resolved Raman spectroscopy data
- Phase Transition Detection: Identify structural phase changes during cycling
- Comprehensive Visualization: 3D strain tensor plots and evolution tracking
- Mode Definitions: A1g, Eg, T2g breathing and framework modes
- Composition Tracking: Li content and chemical disorder analysis
- Electrochemical Synchronization: Correlate with battery state-of-charge
- Degradation Analysis: Monitor cycling-induced structural changes
- Flexible Import: Folder-based or database import with advanced filtering
- Multiple Visualization Methods:
- PCA (Principal Component Analysis)
- UMAP (Uniform Manifold Approximation and Projection)
- Interactive Exploration:
- Dendrogram visualization
- Heatmap analysis
- Scatter plots with cluster highlighting
- Cluster Refinement: K-means and Spectral Clustering with undo functionality
- Polarized Spectra Analysis: Import and analyze orientation-dependent data
- Crystal Orientation Optimization: Calculate and optimize orientation to match experimental data
- All Crystal Symmetries: Support for complete range of crystal systems
- CIF Integration:
- Parse crystallographic information files
- Extract symmetry and atomic positions
- Calculate Raman tensors from crystal structure
- Optional pymatgen integration
- Interactive 3D Ellipsoids: Real-time tensor visualization
- Principal Axes Exploration: Understand tensor orientation
- Crystal Shape Visualization: Point group-specific shapes
- Publication-Quality 3D Exports: Professional graphics for publications
- Random Forest Algorithms: Automated mineral identification
- Dimensionality Reduction: PCA, NMF, t-SNE, UMAP for data exploration
- Template Matching: AI-enhanced template fitting with confidence scoring
- Class Flip Detection: Intelligent detection of misclassified spectra
- Model Management: Save, load, and retrain classification models
- Dynamic Time Warping: Handle spectral shifting and distortions
- Ensemble Methods: Combine multiple algorithms for robust identification
- Uncertainty Quantification: Statistical confidence in ML predictions
session save/restore system in the near future
- Complete Session Recovery: Save and restore entire application state
- Window Layout Preservation: Remember panel positions, zoom levels, and preferences
- Data State Management: Loaded spectra, analysis results, template libraries
- Auto-Save & Crash Recovery: Automatic session backup with crash recovery
- Session Sharing: Export and share complete analysis sessions
- Modern Qt6 Framework: Cross-platform native performance
- Modular Architecture: Extensible design for custom analysis modules
- Multi-Threading: Background processing for responsive interface
- Efficient Memory Management: Handle large datasets without performance loss
- Professional Updates: Built-in update checker with version management
# 1. Install Anaconda from https://www.anaconda.com/products/distribution
# 2. Create Environment
conda create -n ramanlab python=3.9
conda activate ramanlab
# 3. Clone Repository
git clone https://github.com/aaroncelestian/RamanLab.git
cd RamanLab
# 4. Install Dependencies
pip install -r requirements_qt6.txt
# 5. Verify Installation
python check_dependencies.py
# 6. Launch Application
python launch_ramanlab.py# Install desktop shortcuts and application integration
python install_desktop_icon.py
# Creates platform-specific integration:
# Windows: Desktop shortcut with custom icon
# macOS: Application bundle in ~/Applications
# Linux: Desktop entry and applications menu integration# Main RamanLab Application
python launch_ramanlab.py
# Database Browser & Management
python launch_raman_database_browser.py
# 2D Map Analysis (Standalone)
python map_analysis_2d/main.py
# Polarization Analyzer
python launch_orientation_optimizer.py
# Cluster Analysis
python raman_cluster_analysis_qt6.py
# Peak Fitting (Standalone)
python peak_fitting_qt6.py
# Batch Peak Fitting
python batch_peak_fitting_qt6.py
# Line Scan Analysis
python launch_line_scan_splitter.py- Python: 3.8+ (3.9+ recommended)
- RAM: 4GB (8GB+ for large datasets)
- Storage: 2GB free space (5GB+ including databases)
- OS: Windows 10+, macOS 10.14+, Linux (modern distributions)
- Python: 3.9 or 3.10
- RAM: 16GB+ for complex analyses and large maps
- Storage: 10GB+ (including databases and results)
- GPU: Optional, beneficial for machine learning tasks
RamanLab/
├── main_qt6.py # Main application entry point
├── launch_ramanlab.py # Primary application launcher
├── core/ # Core analysis modules
│ ├── database.py # Database management
│ ├── spectrum.py # Spectrum processing
│ ├── peak_fitting.py # Peak fitting algorithms
│ └── state_management/ # Session management system
├── map_analysis_2d/ # 2D mapping analysis suite
├── polarization_ui/ # Polarization analysis tools
├── battery_strain_analysis/ # Battery materials analysis
├── Hey_class/ # Hey-Celestian classification system
├── ml_raman_map/ # Machine learning modules
├── database_browser_qt6.py # Database browser application
├── peak_fitting_qt6.py # Standalone peak fitting
├── batch_peak_fitting_qt6.py # Batch processing tools
├── raman_cluster_analysis_qt6.py # Cluster analysis application
├── docs/ # Comprehensive documentation
├── requirements_qt6.txt # Dependencies list
├── check_dependencies.py # Dependency verification
└── version.py # Version information
-
Qt6 Import Errors:
pip install --upgrade PySide6
-
Missing Dependencies:
python check_dependencies.py pip install -r requirements_qt6.txt
-
Database Files Missing:
- Download from provided figshare links
- Place in main RamanLab directory
- Verify with database browser application
-
Memory Issues:
- Increase system memory for large datasets
- Use batch processing for extensive analyses
- Enable data streaming for map analysis
-
Platform-Specific Issues:
- Check
docs/directory for platform guides - Review cross-platform utilities in
cross_platform_utils.py
- Check
- Import Spectra: File menu or drag-and-drop
- Process Data: Background subtraction and peak detection
- Database Search: Match against reference database using Hey-Celestian classification
- Advanced Analysis: Peak fitting, strain analysis, or polarization analysis
- Export Results: Save as reports, images, or complete sessions
# 1. Launch main application
python launch_ramanlab.py
# 2. Import spectrum and apply Hey-Celestian classification
# 3. Use predicted vibrational modes for targeted analysis
# 4. Validate with database matching
# 5. Export comprehensive identification report# 1. Time-series strain analysis
cd battery_strain_analysis
python demo_limn2o4_analysis.py
# 2. Results include:
# - Strain tensor evolution
# - Composition tracking
# - Phase transition detection
# - 3D visualizationRamanLab welcomes contributions from the scientific community. Areas of particular interest:
- New Classification Systems: Extend Hey-Celestian or develop specialized systems
- Analysis Algorithms: Novel peak fitting, background subtraction, or identification methods
- Database Expansion: Additional reference spectra and metadata
- Specialized Modules: Industry or research-specific analysis tools
- Documentation: User guides, tutorials, and scientific validation
Comprehensive documentation available in the docs/ directory:
- User Manual: Complete application guide
- API Documentation: Developer reference
- Scientific Methods: Algorithmic descriptions and validation
- Installation Guides: Platform-specific setup instructions
- Tutorial Collection: Step-by-step analysis examples
MIT License - see LICENSE file for details
- RRUFF Database (www.rruff.info) - Comprehensive mineral reference spectra
- SLOPP/SLOPP-E - Plastic and polymer spectral libraries
- WURM Database - DFT calculations and theoretical Raman spectra
- Qt Project - Modern cross-platform GUI framework (PySide6)
- Python Scientific Stack - NumPy, SciPy, Matplotlib, scikit-learn, and pandas
- Scientific Community - Raman spectroscopy research and methodology development
- Natural History Museum of Los Angeles County - Institutional support
- International Raman Community - Feedback, validation, and collaborative development
Aaron J. Celestian, Ph.D.
Curator of Mineral Sciences
Natural History Museum of Los Angeles County
Dr. Celestian specializes in mineral physics and crystallography with extensive experience in vibrational spectroscopy applications. His research focuses on the relationship between crystal structure and physical properties, making him uniquely qualified to develop the revolutionary Hey-Celestian classification system that bridges traditional mineralogy with modern spectroscopic analysis.
For the latest updates, detailed documentation, and scientific publications related to RamanLab, visit our documentation directory or check the individual module README files.
RamanLab - Advancing Raman Spectroscopy Through Innovation