Getting Started

This guide will help you get started with xpectrass for FTIR spectral data analysis.

Prerequisites

  • Python 3.8+

  • NumPy, SciPy, Pandas, Polars

  • PyBaselines, PyWavelets

  • Matplotlib, scikit-learn

Installation

From PyPI

pip install xpectrass

From Source

git clone https://github.com/kazilab/xpectrass.git
cd xpectrass
pip install -e .

Quick Start

Option 1: Use Bundled Datasets

Xpectrass comes with 6 pre-loaded FTIR plastic datasets:

from xpectrass import FTIRdataprocessing
from xpectrass.data import load_jung_2018, get_data_info

# See available datasets
print(get_data_info())

# Load a dataset
df = load_jung_2018()

# Remove duplicate spectra
df = df.drop_duplicates(subset=['sample_id'])
print(f"Loaded {len(df)} spectra")

# Start preprocessing
ftir = FTIRdataprocessing(df, label_column="type")

Option 2: Load Your Own Data

from xpectrass import FTIRdataprocessing
from xpectrass.utils import process_batch_files
import glob
import pandas as pd

# Load single CSV file
df = pd.read_csv("ftir_data.csv", index_col=0)

# Or load multiple files
files = glob.glob('data/plastics/*.csv')
df = process_batch_files(files)

print(f"Loaded {len(df)} spectra with {len(df.columns)-1} wavenumbers")

Data Format:

  • Rows: Individual spectra

  • Columns: One label column + wavenumber columns (e.g., “400.0”, “401.0”, …)

  • Index: Sample names or IDs

Example CSV structure:

sample_id,type,400.0,401.0,402.0,...,4000.0
HDPE_001,HDPE,0.123,0.125,0.128,...,0.045
PP_001,PP,0.098,0.102,0.105,...,0.038

Basic Preprocessing Workflow

Step-by-Step Approach

from xpectrass import FTIRdataprocessing

# Initialize
ftir = FTIRdataprocessing(
    df,
    label_column="type",  # Name of your label column
    wn_min=400,           # Minimum wavenumber
    wn_max=4000           # Maximum wavenumber
)

# Step 1: Convert to absorbance (if data is in transmittance)
ftir.convert(mode="to_absorbance", plot=True)

# Step 2: Evaluate and apply denoising
ftir.find_denoising_method(n_samples=50, plot=True)
ftir.denoise_spect(method="savgol", window_length=15)

# Step 3: Evaluate and apply baseline correction
ftir.find_baseline_method(n_samples=50, plot=True)
ftir.plot_rfzn_nar_snr(metric_name="SNR")  # Visualize evaluation metrics
ftir.correct_baseline(method="asls", plot=False)

# Step 4: Remove atmospheric interference (CO₂, H₂O)
ftir.exclude_interpolate(method="spline", plot=True)

# Step 5: Evaluate and apply normalization
ftir.find_normalization_method()
ftir.normalize(method="snv")

# Step 6: Compare all processing stages
ftir.plot_multiple_spec()

# Get processed data
processed_df = ftir.df_norm

Quick Run with Defaults

For rapid prototyping:

ftir = FTIRdataprocessing(df, label_column="type")

# Run entire pipeline with default settings
ftir.run()

# Get final processed data
processed_df = ftir.df_norm

Basic Analysis Workflow

After preprocessing, use FTIRdataanalysis for visualization and machine learning:

from xpectrass import FTIRdataanalysis

LABEL_COLUMN = "type"
MIN_SAMPLE_NUMBER_FOR_GROUP = 10
# remove small groups from processed data
processed_df = processed_df.dropna(subset=[LABEL_COLUMN])
group_counts=processed_df[LABEL_COLUMN].value_counts()
valid_groups = group_counts[group_counts >= MIN_SAMPLE_NUMBER_FOR_GROUP].index
processed_df = processed_df[processed_df[LABEL_COLUMN].isin(valid_groups)]

# Initialize analysis
analysis = FTIRdataanalysis(processed_df, label_column=LABEL_COLUMN)

# Visualize mean spectra by class
analysis.plot_mean_spectra()

# Plot spectral heatmap
analysis.plot_heatmap()

# Dimensionality reduction
analysis.plot_pca()
analysis.plot_tsne()
analysis.plot_umap()

# Statistical analysis
analysis.perform_anova()
analysis.plot_correlation()

Machine Learning

# Prepare data for ML
analysis.ml_prepare_data()

# Run all classification models
results = analysis.run_all_models()
print(results.sort_values('test_f1', ascending=False))

# Tune top performing models
tuned_results = analysis.model_parameter_tuning()

# Explain model predictions with SHAP
analysis.explain_by_shap()
analysis.local_shap_plot()

Key Methods Quick Reference

FTIRdataprocessing

Method

Purpose

convert()

Transmittance ↔ Absorbance conversion

exclude_interpolate()

Remove atmospheric interference

find_baseline_method()

Evaluate baseline correction methods

correct_baseline()

Apply baseline correction

find_denoising_method()

Evaluate denoising methods

denoise_spect()

Apply denoising

find_normalization_method()

Evaluate normalization methods

normalize()

Apply normalization

derivatives()

Calculate spectral derivatives

plot_multiple_spec()

Compare all processing stages

run()

Execute full pipeline with defaults

FTIRdataanalysis

Method

Purpose

plot_mean_spectra()

Plot mean spectra by class

plot_pca()

PCA analysis

plot_tsne()

t-SNE analysis

plot_umap()

UMAP analysis

plot_plsda()

PLS-DA analysis

perform_anova()

ANOVA statistical test

ml_prepare_data()

Prepare train/test split

run_all_models()

Evaluate all ML models

model_parameter_tuning()

Tune hyperparameters

explain_by_shap()

SHAP explainability

Getting Help