Skip to content

SpectraSherpa User Manual

Overview

SpectraSherpa is an integrated platform for spectroscopic data analysis, synthesis, and workflow automation. This manual covers how to load different data sources and synthesize spectral data.

Table of Contents

  1. Loading SpectroChemPy Data (Experiments)
  2. Loading NIST Reference Spectra
  3. Loading 96-Well Essential Oil Data
  4. Loading DOE Calibration Data (Project 1)
  5. Synthesizing Data with the Builder
  6. Workflow Builder
  7. Status Indicators

1. Loading SpectroChemPy Data (Experiments)

The Experiments module manages experimental spectra with versioning and metadata tracking.

Creating a New Experiment

  1. Navigate to Experiments in the sidebar
  2. Click the Create tab
  3. Fill in the experiment details:
  4. Name: Descriptive name for your experiment
  5. Description: Purpose and notes
  6. Hardware: Spectrometer used (optional)
  7. DOE Setup: Link to Design of Experiments configuration (optional)
  8. Click Create Experiment

Uploading Spectra Files

  1. Select an experiment from the Overview tab
  2. Switch to the Files tab
  3. Choose the file stage:
  4. Raw: Original unprocessed spectra
  5. Preprocessed: Cleaned/corrected spectra
  6. Synthetic: Generated/blended spectra
  7. Drag and drop files or click to browse
  8. Supported formats:
  9. CSV (wavenumber, absorbance columns)
  10. JCAMP-DX (.jdx, .dx)
  11. SPC files
  12. SpectroChemPy native formats

Version Management

  1. Go to the Versions tab
  2. Click Create Version to snapshot current state
  3. Enter version name and description
  4. To restore: click the restore icon on any version

Loading Experiment Data in Builder

Once files are uploaded, they become available in the Synthesis module: 1. Go to Synthesis > Preprocess tab 2. Select your experiment from the dropdown 3. Choose files to preprocess

2. Loading NIST Reference Spectra

The Library module provides access to NIST WebBook reference spectra.

Searching NIST Database

  1. Navigate to Library in the sidebar
  2. Use the Search tab
  3. Type a compound name (e.g., "ethanol", "limonene")
  4. Results show:
  5. Compound name
  6. CAS number
  7. NIST identifier

Downloading Spectra

  1. From search results, click Download for standard resolution
  2. Or click High-Res for higher resolution data
  3. Download progress appears in the right panel
  4. Downloads are queued and processed in background

Viewing Library Entries

  1. Switch to the Library tab
  2. Browse all downloaded spectra
  3. Click any entry to view:
  4. Interactive spectrum plot
  5. Wavenumber range
  6. Resolution details
  7. Download date

Using Library Spectra in Synthesis

  1. In the Library tab, select spectra for blending
  2. Click Add to Builder
  3. Navigate to Synthesis to use them

3. Loading 96-Well Essential Oil Data

The DOE (Design of Experiments) tab in Experiments manages 96-well plate configurations for essential oil analysis.

Setting Up the Sample Database

  1. Navigate to Experiments > select your experiment
  2. Go to the DOE tab
  3. In the Sample Database section:
  4. Click Import CSV to bulk import samples
  5. Or manually add samples with:
    • Sample ID
    • Name (e.g., "Lavender EO", "Peppermint EO")
    • Type (essential_oil, carrier, standard)
    • Brand/Source
    • CAS Number (if applicable)

Creating Mixtures

  1. In the Mixtures section, click New Mixture
  2. Select component samples from the database
  3. Specify composition:
  4. Weight %: Mass-based percentages
  5. Mole %: Molar percentages
  6. Volume %: Volume-based percentages
  7. Name the mixture (e.g., "Blend A - 50% Lavender, 50% Peppermint")

Assigning Wells on the 96-Well Plate

  1. In the 96-Well Plate Map section:
  2. Visual grid shows all 96 wells (A1-H12)
  3. Select a mixture from the dropdown
  4. Click wells to assign that mixture
  5. Color coding shows different mixtures
  6. Plate Statistics show:
  7. Assigned wells count
  8. Empty wells count
  9. Mixture distribution

Matching Acquisition Files to Wells

  1. Upload your spectra files in the Files tab
  2. Return to DOE > Acquisition Matching section
  3. Click Auto-Match to automatically match files to wells
  4. Matching uses filename patterns to identify:
  5. Well position (e.g., "A1", "B12")
  6. Sequence number
  7. Replicate information
  8. Review and manually correct any mismatches

Loading 96-Well Data in Builder

  1. Go to Synthesis > Preprocess tab
  2. Select your 96-well experiment
  3. Files are organized by well position
  4. Select wells/files to preprocess together

4. Loading DOE Calibration Data (Project 1)

DOE Configurations store structured experimental designs for calibration studies.

Creating a DOE Configuration

  1. Navigate to Experiments > DOE tab
  2. Or access DOE Configs directly

Defining Experimental Factors

  1. In the Experimental Factors section:
  2. Add Sample Factors:
  3. Concentration levels
  4. Component ratios
  5. Sample types
  6. Add Method Factors:
  7. Temperature
  8. Integration time
  9. Number of scans
  10. For each factor, specify:
  11. Name
  12. Type (categorical or continuous)
  13. Levels (e.g., [0, 25, 50, 75, 100] for concentration %)

Setting Up Run Sequences

  1. In the Run Sequence section:
  2. Define the order of experimental runs
  3. Each run includes:
  4. Sequence order
  5. Factor level values
  6. Folder path for data files
  7. Batch identifier

Loading Calibration Data

  1. Upload calibration spectra files to the experiment
  2. Match files to run sequences in Acquisition Matching
  3. The system links:
  4. Spectra files
  5. Well positions (if applicable)
  6. Factor values (concentrations, conditions)

Using Calibration Data in Builder

  1. Go to Synthesis > Preprocess tab
  2. Select the calibration experiment
  3. Files are available with their associated metadata
  4. Use for:
  5. Building calibration curves
  6. Creating synthetic mixtures
  7. Validating models

5. Synthesizing Data with the Builder

The Synthesis module creates synthetic spectra by blending reference species.

Preprocess Tab

Purpose: Clean and prepare spectra before blending.

Loading Spectra

  1. From Experiments: Select experiment and files
  2. From Library: Add NIST reference spectra
  3. Both sources can be combined

Preprocessing Settings

Setting Description Default
Alignment Method Wavenumber interpolation (pchip, linear, sinc) pchip
Apply Range Limit Clip to wavenumber range Off
Min/Max Wavenumber Range bounds (cm^-1) 400-4000
Cosmic Ray Removal Remove spike artifacts On
Savitzky-Golay Smoothing Noise reduction filter On
Clip Floor Set minimum absorbance value Off

Running Preprocessing

  1. Configure settings
  2. Click Run Preprocessing
  3. View results in the plot panel
  4. Each spectrum shows as a separate trace

Blend Tab

Purpose: Combine species spectra with concentration profiles.

Selecting Species

  1. Preprocessed spectra appear as available species
  2. Check species to include in blend
  3. Each species represents a pure component

Defining Concentration Profiles

Create time-series concentrations for each species:

Species A: [100, 80, 60, 40, 20, 0]    (decreasing)
Species B: [0, 20, 40, 60, 80, 100]    (increasing)
Species C: [50, 50, 50, 50, 50, 50]    (constant)

Concentration Curve Editor: 1. Select a species 2. Draw curve points on the canvas 3. Or enter values numerically 4. Curves are interpolated between points

Blending Options

Option Description
Pathlength (m) Optical pathlength for Beer's Law
Absorption Coefficient Molar absorptivity
Time Steps Number of blend time points

Running the Blend

  1. Configure concentrations for all species
  2. Click Blend Spectra
  3. Result shows:
  4. Time-series of blended spectra
  5. 3D surface plot (wavenumber x time x absorbance)
  6. Individual time slices

Export Tab

Purpose: Save synthetic data for external use.

Export Formats

Format Use Case
CSV Spreadsheet analysis, simple import
JSON Web applications, metadata preservation
NetCDF Scientific computing, large datasets
Python Script Reproducibility, automation

Export Options

  1. Select output format
  2. Choose data to include:
  3. Preprocessed spectra
  4. Blended results
  5. Concentration profiles
  6. Full metadata
  7. Click Export
  8. File downloads to your system

6. Workflow Builder

The Workflow Builder creates visual analysis pipelines.

Adding Nodes

From the left toolbar, click to add nodes:

Category Nodes
Data Load Data
Preprocess Normalize, Scale, Baseline, Smooth
Analysis PCA, PLS, MCR-ALS
Stats Statistics
Visualize Scatter Plot
Export Export

Connecting Nodes

  1. Click Connect on a source node
  2. Click Connect Here on the target node
  3. Arrow shows data flow direction

Configuring Nodes

  1. Click a node to select it
  2. Inspector panel shows parameters
  3. Adjust settings as needed:
  4. Normalization method
  5. Number of components
  6. Output format

Executing Workflows

  1. Click Execute Workflow
  2. Nodes process in topological order
  3. Status shows:
  4. Pending (gray circle)
  5. Processing (yellow, animated)
  6. Complete (green checkmark)
  7. Results display in inspector panel

Exporting Python Code

  1. Click Export Python
  2. Downloads executable Python script
  3. Uses SpectroChemPy for full compatibility

7. Status Indicators

The top bar shows four status lights:

Position Indicator Colors
1st Data Green: Sources available / Gray: No experiments
2nd Workflow Green: Ready / Yellow: Unsaved changes / Gray: Empty
3rd LLM Green: Connected / Yellow: Connecting / Red: Disconnected
4th Compute Blue: Local

Hover over any indicator for detailed status.

Quick Start Workflow

Example: Essential Oil Blend Analysis

  1. Create Experiment

  2. Experiments > Create > "Essential Oil Study"

  3. Set Up 96-Well Plate

  4. DOE tab > Import samples
  5. Create mixtures

  6. Assign wells

  7. Upload Spectra

  8. Files tab > Upload raw spectra

  9. Match to wells in DOE > Acquisition Matching

  10. Add Reference Spectra

  11. Library > Search "limonene", "linalool"

  12. Download reference spectra

  13. Preprocess

  14. Synthesis > Preprocess tab
  15. Select experiment files + library references
  16. Apply smoothing, baseline correction

  17. Run Preprocessing

  18. Blend

  19. Blend tab > Select species
  20. Define concentration profiles

  21. Run Blend

  22. Analyze

  23. Workflow Builder > Add PCA node
  24. Connect to data

  25. Execute and view results

  26. Export

  27. Export tab > Download CSV/Python script

Keyboard Shortcuts

Shortcut Action
Ctrl+S Save current work
Ctrl+Z Undo
Ctrl+Shift+Z Redo
Delete Remove selected node
Escape Cancel current operation

Troubleshooting

Common Issues

"No experiments loaded" - Create an experiment first - Check that files are uploaded

"LLM Disconnected" - Check backend server is running - Verify WebSocket connection

"Workflow execution failed" - Check node connections - Verify data node has valid source - Review error message in toast

"NIST download stuck" - Check internet connection - NIST may rate-limit requests - Try again after a few minutes

Support

For issues and feature requests, visit: https://github.com/Spectra-Scientific-LLC/Spectra-Sherpa/issues