STLAR: Spatio-Temporal LFP Analyzer

STLAR (or Stellar) combines temporal HFO detection, spatial spectral mapping, and optional deep learning workflows.

---

Quickstart

• Preferred Python: 3.12 (Conda recommended)

conda create -n stlar python=3.12
conda activate stlar
pip install -r requirements.txt

Run GUI:

python -m stlar gui

Run a simple CLI batch:

python -m stlar hilbert-batch -f path/to/data/

Windows reset tip (DLL / _ctypes issues after Python changes):

conda env remove -n stlar
conda create -n stlar python=3.12
conda activate stlar
pip install -r requirements.txt

---

📑 Table of Contents

Getting Started

• Quickstart
• Installation
• Features
• Choose Your Workflow

Usage

• GUI Workflow
• CLI Reference
  • Detection Methods
• HFO Metrics & Score Filtering
• Spatial Mapping (batch-ssm)
• Complete Deep Learning Training Workflow

Advanced Docs

• Advanced CLI Guide
• Advanced DL Training Guide
• Consensus Detection
• Detection Tuning
• Technical Reference

Support

• Troubleshooting Installation
• Getting Help
• Recent Changes

---

Features

Temporal Analysis

• HFO detection (Hilbert, STE, MNI, Consensus, Deep Learning)
• Scoring and event review workflow
• Time-frequency analysis (Stockwell transform)

Spatial Analysis

• Arena heatmaps and trajectory-aware mapping
• PSD across positions and chunks
• Optional binned exports for downstream analysis

Deep Learning

• Prepare training segments from EOIs
• Train and export custom models
• Use trained models in dl-batch

---

Installation

Requirements

• Python 3.10–3.13 supported (3.12 preferred)
• pip
• ~2-3 GB free disk

Install

git clone https://github.com/HussainiLab/STLAR.git
cd STLAR

conda create -n stlar python=3.12
conda activate stlar
pip install -r requirements.txt

Optional editable install:

pip install -e .

Deep Learning optional dependencies

CPU:

pip install torch onnxruntime

GPU (CUDA 11.8):

pip install --index-url https://download.pytorch.org/whl/cu118 torch torchvision torchaudio
pip install onnxruntime-gpu

Troubleshooting Installation

• python not found: try python3
• Conda not activating: run conda init, restart terminal
• Import errors: verify env active, rerun pip install -r requirements.txt --upgrade

---

Choose Your Workflow

1. GUI-first (recommended): python -m stlar gui
2. CLI batch processing: python -m stlar <command> ...
3. DL workflow: prepare-dl → train-dl → export-dl → dl-batch

Recommended order for new users:

• Start with GUI Workflow
• Then use CLI Reference
• Use advanced docs only when needed:
  • Advanced CLI Guide
  • Advanced DL Training Guide

---

GUI Workflow

Launch:

python -m stlar gui

Basic flow:

1. Import .set / session folder
2. Open Graph Settings and choose source .eeg / .egf
3. Open HFO Detection → Automatic Detection tab
4. Run detection (Hilbert / STE / MNI / Consensus / DL)
5. Move selected EOIs to Score tab
6. Label and save scores

Spatial GUI:

python -m stlar spatial-gui

---

CLI Reference

STLAR CLI format:

python -m stlar <command> [options]

Quick command groups:

• Detection: hilbert-batch, ste-batch, mni-batch, consensus-batch, dl-batch
• Analysis: metrics-batch, filter-scores, batch-ssm
• DL pipeline: prepare-dl, train-dl, export-dl

Basic examples:

python -m stlar hilbert-batch -f data/
python -m stlar consensus-batch -f data/ -v
python -m stlar dl-batch -f data/ --model-path models/hfo_detector.pt

Detection Methods

• Hilbert: fast baseline detector for common ripple workflows
• STE: RMS-window energy detector
• MNI: percentile/baseline-driven detector
• Consensus: combines Hilbert + STE + MNI voting
• DL: model-based detection from exported .pt / .onnx (supports both 1D and CWT 2D models)

For full parameter tables and advanced recipes, see Advanced CLI Guide.

---

HFO Metrics & Score Filtering

Basic examples:

python -m stlar metrics-batch -f HFOScores/ -v
python -m stlar filter-scores -f HFOScores/session_HIL.txt --min-duration-ms 15 --max-duration-ms 120

Use this after detection to summarize event rates/durations and clean score files.

Advanced options (presets, behavior gating, custom speed thresholds):

• Advanced CLI Guide

---

Spatial Mapping (batch-ssm)

Basic examples:

python -m stlar batch-ssm data/session.egf --ppm 595
python -m stlar batch-ssm data/ --ppm 595 --chunk-size 60

Optional exports:

python -m stlar batch-ssm data/ --ppm 595 --export-binned-csvs --plot-trajectory

Advanced spatial mapping usage and output details:

• Advanced CLI Guide

---

Complete Deep Learning Training Workflow

Minimal 4-step flow:

1. Prepare segments/manifests
2. Train model
3. Export model
4. Run dl-batch on new data

Basic commands:

python -m stlar prepare-dl --eoi-file detections.txt --egf-file recording.egf --output training_data --split-train-val
python -m stlar train-dl --train training_data/manifest_train.csv --val training_data/manifest_val.csv --epochs 15 --out-dir models
python -m stlar export-dl --ckpt models/best.pt --ts models/model.pt --onnx models/model.onnx
python -m stlar dl-batch -f new_recordings/ --model-path models/model.pt --threshold 0.5

CWT models: If you trained with --use-cwt, you must use --use-cwt --fs <Hz> during detection:

python -m stlar train-dl --train data/manifest_train.csv --val data/manifest_val.csv --use-cwt --fs 4800 --epochs 15 --out-dir models
python -m stlar export-dl --ckpt models/best.pt --ts models/cwt_model.pt
python -m stlar dl-batch -f new_recordings/ --model-path models/cwt_model.pt --use-cwt --fs 4800 --threshold 0.5

Advanced training topics (CWT, batch training, GUI monitoring, tuning, troubleshooting):

• Advanced DL Training Guide

Cross-link: advanced guide points back to this quick workflow.

---

Module Structure

Temporal Analysis (HFO Detection)

• Location: hfoGUI/ and stlar/
• Entry: python -m stlar
• Docs: Consensus Quickstart, Consensus Detection

Spatial Analysis

• Location: spatial_mapper/
• Entry: python -m stlar spatial-gui or python -m stlar batch-ssm
• Docs: Advanced CLI Guide (Spatial Mapping), Technical Reference

Deep Learning

• Location: hfoGUI/dl_training/
• Entry: prepare-dl, train-dl, export-dl, dl-batch
• Docs: Advanced DL Training Guide, Training Visualization

Original Tools

This project unifies:

• hfoGUI
• Spatial_Spectral_Mapper

Documentation

Core Guides

• Advanced CLI Guide
• Advanced DL Training Guide
• Technical Reference
• Consensus Detection
• Consensus Quickstart
• Detection Tuning
• Containerization Guide

GUI / DL / CWT

• GUI Quickstart
• Training Visualization
• CWT Debug Guide
• Preset Gating Guide

API Documentation

For developer-oriented APIs and internals:

• Technical Reference
• hfoGUI/core/
• hfoGUI/dl_training/
• spatial_mapper/src/

Getting Help

• Check Troubleshooting Installation
• Use GUI Quickstart for first-run issues
• Use Advanced CLI Guide for command options
• Use Advanced DL Training Guide for model pipeline issues

Recent Changes

• Fixed: dl-batch now supports CWT mode via --use-cwt --fs <Hz> flags (matches training pipeline)
• README simplified for quicker onboarding
• Advanced CLI details moved to docs/CLI_ADVANCED.md
• Advanced DL workflow details moved to docs/DL_TRAINING_ADVANCED.md

---

GPL-3.0 License - see LICENSE for details.