DOCSEARCHbyAlgolia
Submit Docs

RamanSPy

repository·main·Indexed 41 days ago

https://github.com/barahona-research-group/ramanspy

An open-source Python package for integrative Raman spectroscopy data analysis. Version 0.2.10 provides tools for data loading, preprocessing pipelines (cropping, despiking, denoising, baseline correction, and normalization), spectral unmixing (NFINDR, PPI, FIPPI, VCA), decomposition (PCA, NMF, ICA), and clustering (KMeans). It includes a visualization module for spectra, volumes, and images, and is designed for integration with machine learning frameworks like Scikit-learn.

Tokens
60.3K
Snippets
232
Records
278
Agent score
50%

What's inside RamanSPy

  1. Overview of RamanSPy features

    main

    RamanSPy is an open-source Python library designed for Raman spectroscopic research and analysis. It provides tools to accelerate day-to-day analyses, research applications, and the development/validation of new spectroscopic algorithms.

    Key capabilities include:

    • Data Management: Common data formats, data loaders, and datasets.
    • Preprocessing: Individual preprocessing methods, pipelining, and preprocessing protocols.
    • Analysis: Various analysis methods, AI/ML integration, and metrics.
    • Data Generation: Synthetic data generators.
    • Visualization: Specialized tools for plotting Raman spectra and results.

  2. Explore RamanSPy application examples

    main

    RamanSPy provides several example workflows for different Raman spectroscopy analytics tasks. Key application areas demonstrated in the documentation include:

    • Package Overview: Hyperspectral unmixing of Raman spectroscopic data for biomolecular composition analysis.
    • Preprocessing Pipelines: Constructing, customizing, and reusing preprocessing pipelines.
    • AI-based Denoising: Using deep learning models for spectral denoising.
    • Bacteria Classification: Benchmarking machine learning models for classification tasks.

  3. Measure spectral similarity with ramanspy.metrics

    main

    The ramanspy.metrics module provides several functions to quantify the similarity between spectra. These metrics are primarily used to evaluate the performance of different preprocessing or analysis methods by comparing processed spectra against ground truth or reference spectra.

    Available metrics include:

    • MAE: Mean Absolute Error
    • MSE: Mean Squared Error
    • RMSE: Root Mean Squared Error
    • SAD: Spectral Angle Distance
    • SID: Spectral Information Divergence

  5. Perform spectral analysis with RamanSPy

    main

    RamanSPy provides standardized classes for various spectral analysis tasks, including decomposition, clustering, and spectral unmixing. These analysis methods are part of the ramanspy.analysis module and follow a consistent interface: they can be applied to Raman spectroscopic data using the .apply() method. This design allows you to readily access and apply these algorithms to any data type loaded into the RamanSPy framework.

    # Conceptual usage pattern
analysis_method.apply(data)

  6. How preprocessing steps and pipelines work in RamanSPy

    main

    In RamanSPy, all preprocessing operations—whether they are single algorithms or complex sequences—are standardized using the PreprocessingStep abstraction.

    • PreprocessingStep: This is the base class for all individual preprocessing algorithms (e.g., denoising, baseline correction). Because they all follow this interface, they are data-agnostic and can be applied to any Raman spectroscopic data loaded into the framework.
    • Pipeline: A Pipeline is a collection of PreprocessingStep instances stacked together. A Pipeline itself acts as a single PreprocessingStep, meaning you can nest pipelines within other pipelines to create multi-layered preprocessing workflows.

    This architecture allows you to move from simple single-step corrections to complex, multi-stage protocols using a consistent interface.

  7. Integrate RamanSPy data with TensorFlow for Neural Network classification

    main

    RamanSPy is designed to be integrable with the Python machine learning ecosystem. To use RamanSPy data with frameworks like TensorFlow, you can access the underlying spectral data using the .flat.spectral_data attribute of the RamanSPy dataset container. This allows you to pass the data directly into standard ML training pipelines (e.g., model.fit()) and prediction methods (e.g., model.predict()).

    Workflow Example:

    1. Load data with ramanspy.datasets.
    2. Extract spectral data using X.flat.spectral_data.
    3. Shuffle data using sklearn.utils.shuffle.
    4. Train a model (e.g., Keras/TensorFlow) using the extracted arrays.
    5. Predict and evaluate using standard libraries like sklearn.metrics.
    import tensorflow as tf
import ramanspy
from sklearn.utils import shuffle

# 1. Load
dir_ = r"../../../../data/bacteria_data"
X_train, y_train = ramanspy.datasets.bacteria("val", folder=dir_)

# 2. Extract and Shuffle
X_train, y_train = shuffle(X_train.flat.spectral_data, y_train)

# 3. Train (using a standard TF model)
# ... model definition ...
model.fit(X_train, y_train, epochs=15, batch_size=32)

# 4. Predict
y_pred = model.predict(X_test.flat.spectral_data)

  8. Use `ramanspy.SpectralContainer` for generic data storage

    main

    The ramanspy.SpectralContainer is the core data management class in RamanSPy. It acts as a generic container for Raman spectroscopic data of any dimension.

    While you can use SpectralContainer for any data shape, RamanSPy provides specialized subclasses for common Raman data types:

    • ramanspy.Spectrum: For single spectra.
    • ramanspy.SpectralImage: For imaging data.
    • ramanspy.SpectralVolume: For volumetric data.

    All these specialized classes inherit from SpectralContainer and share its features.

    import numpy as np
import ramanspy

# Define a spectral axis (e.g., wavenumbers)
spectral_axis = np.linspace(100, 3600, 1500)

# Define intensity data (e.g., shape (20, 1500) for 20 spectra)
spectral_data = np.random.rand(20, 1500)

# Wrap into a SpectralContainer
raman_object = ramanspy.SpectralContainer(spectral_data, spectral_axis)

  9. How to use `plot_type` in `mean_spectra`

    main

    The ramanspy.plot.mean_spectra method uses the plot_type argument to control how different groups of spectra are laid out visually:

    1. plot_type='single': Overlays all provided groups onto a single set of axes. This is useful for direct comparison of mean shifts and confidence intervals.
    2. plot_type='separate': Generates a collection of separate axes (plots), one for each group. This improves readability when groups have very different scales or complex features.
    3. plot_type='stacked': Generates a single figure containing multiple axes, where each group is plotted in its own subplot, arranged vertically. This is ideal for comparing distributions without the visual clutter of overlapping lines.
    4. plot_type='single stacked': Overlays the groups in a single set of axes but uses a stacked visual style to differentiate them.
    # Single overlaid plot
ramanspy.plot.mean_spectra(groups, plot_type='single')

# Separate subplots
ramanspy.plot.mean_spectra(groups, plot_type='separate')

# Vertically stacked subplots
ramanspy.plot.mean_spectra(groups, plot_type='stacked')

# Single overlaid stacked plot
ramanspy.plot.mean_spectra(groups, plot_type='single stacked')

  10. Construct preprocessing pipelines with `ramanspy.preprocessing.Pipeline`

    main

    You can construct, customize, and reuse preprocessing protocols by creating a ramanspy.preprocessing.Pipeline object. This object accepts a list of preprocessing steps (such as cropping, despiking, denoising, baseline correction, and normalization) and applies them sequentially to your spectra using the .apply() method.

    Common preprocessing components include:

    • Cropping: ramanspy.preprocessing.misc.Cropper(region=(min, max))
    • Despiking: ramanspy.preprocessing.despike.WhitakerHayes()
    • Denoising: ramanspy.preprocessing.denoise.Gaussian() or ramanspy.preprocessing.denoise.SavGol(window_length=n, polyorder=m)
    • Baseline Correction: ramanspy.preprocessing.baseline.ASLS(), ramanspy.preprocessing.baseline.ASPLS(), or ramanspy.preprocessing.baseline.Poly(poly_order=n)
    • Normalization: ramanspy.preprocessing.normalise.AUC(pixelwise=True), ramanspy.preprocessing.normalise.MinMax(pixelwise=True), or ramanspy.preprocessing.normalise.Vector(pixelwise=True)
    import ramanspy

# Define the pipeline steps
pipe = ramanspy.preprocessing.Pipeline([
    ramanspy.preprocessing.misc.Cropper(region=(700, 1800)),
    ramanspy.preprocessing.despike.WhitakerHayes(),
    ramanspy.preprocessing.denoise.Gaussian(),
    ramanspy.preprocessing.baseline.ASLS(),
    ramanspy.preprocessing.normalise.AUC(pixelwise=True),
])

# Apply the pipeline to your spectra
preprocessed_spectra = pipe.apply(random_spectra)

  11. Extend RamanSPy with custom data loading functions

    main

    To support a new or proprietary file format, you can define a custom data loading function. This function must parse the spectroscopic files and return one of the following RamanSPy data containers:

    • SpectralContainer
    • Spectrum
    • SpectralImage
    • SpectralVolume

    Once the data is loaded into these containers, it is fully compatible with the rest of the RamanSPy workflow, including preprocessing, analysis, and visualization.

  12. Relationship between `Spectrum` and `SpectralContainer`

    main

    In RamanSPy, ramanspy.Spectrum is a specialized subclass of ramanspy.SpectralContainer.

    • SpectralContainer: Provides the core data management and container-level functionality.
    • Spectrum: Inherits all SpectralContainer features but adds specific capabilities like the .plot() method optimized for single spectra/slices.