python-intan 0.0.3

Python interface and utilities for working with Intan RHX devices and electrophysiology data

Python Intan

python-intan is a comprehensive Python package for working with Intan Technologies RHX systems and electrophysiology data. From file loading to real-time streaming, signal processing to machine learning, hardware integration to GUI applications—everything you need for EMG/neural data analysis in one package.

---

✨ Key Features

• 📁 File I/O: Load .rhd, .rhs, .dat, .csv, and .npz files with ease
• 🔴 Real-time Streaming: TCP interface for live data acquisition from RHX devices
• 🎛️ Signal Processing: Filtering, normalization, RMS, feature extraction
• 🤖 Machine Learning: Complete gesture classification pipeline with TensorFlow
• 📊 Visualization: Waterfall plots, real-time plotting, GUI applications
• 🔌 Hardware Integration: LSL support, Raspberry Pi Pico, robotic control
• 🖥️ GUI Applications: EMG viewer, trial selector, gesture pipeline interface
• 🚀 Performance: GPU acceleration, optimized for real-time applications

---

📚 Quick Links

• Documentation - Full guides and API reference
• Examples - 60+ code examples
• FAQ - Frequently asked questions
• Contributing - How to contribute
• Changelog - Version history

---

📦 Installation

From PyPI (Recommended)

pip install python-intan

From Source (Latest Features)

git clone https://github.com/Neuro-Mechatronics-Interfaces/python-intan.git
cd python-intan
pip install -e .

With Virtual Environment

# Using conda
conda create -n intan python=3.10
conda activate intan
pip install python-intan

# Or using venv
python -m venv intan
source intan/bin/activate  # Windows: intan\Scripts\activate
pip install python-intan

GPU Support (Optional)

For faster machine learning training:

pip install tensorflow[and-cuda] nvidia-cudnn-cu12

---

🚀 Getting Started

Load and Visualize EMG Data

import intan

# Load .rhd file (opens file picker)
result = intan.io.load_rhd_file()

# Or specify path directly
result = intan.io.load_rhd_file('path/to/file.rhd')

# Access data
emg_data = result['amplifier_data']  # Shape: (channels, samples)
fs = result['frequency_parameters']['amplifier_sample_rate']
t = result['t_amplifier']

# Quick filtering
emg_filtered = intan.processing.notch_filter(emg_data, fs, f0=60)
emg_filtered = intan.processing.filter_emg(emg_filtered, 'bandpass', fs,
                                            lowcut=10, highcut=500)

# Visualize
intan.plotting.waterfall(emg_filtered, range(64), t,
                         plot_title='Filtered EMG Data')

Real-time Streaming from RHX Device

from intan.interface import IntanRHXDevice

# Connect to device
device = IntanRHXDevice()
device.enable_wide_channel(range(64))
device.start_streaming()

# Stream data
timestamps, data = device.stream(duration_sec=1.0)
print(f"Acquired data shape: {data.shape}")

device.close()

Train a Gesture Classifier

from intan.ml import ModelManager
import numpy as np

# Load training data
data = np.load('training_data.npz')
X_train, y_train = data['features'], data['labels']

# Train model
manager = ModelManager()
model, pca, scaler = manager.train_model(X_train, y_train,
                                          model_type='CNN', epochs=50)

# Save for later use
manager.save_model('gesture_model.keras')

Real-time Gesture Recognition

from intan.interface import IntanRHXDevice
from intan.ml import EMGRealTimePredictor
import tensorflow as tf

# Load trained model
model = tf.keras.models.load_model('gesture_model.keras')

# Initialize device
device = IntanRHXDevice(num_channels=128)
device.start_streaming()

# Create predictor
predictor = EMGRealTimePredictor(device, model, pca, mean, std, label_names)
predictor.run_prediction_loop()

# Get predictions
while True:
    prediction = predictor.get_prediction()
    if prediction:
        print(f"Gesture: {prediction['label']} ({prediction['confidence']:.1%})")

Lab Streaming Layer (LSL) Integration

from intan.interface import IntanRHXDevice, LSLPublisher

# Start device
device = IntanRHXDevice(num_channels=64)
device.start_streaming()

# Publish to LSL
publisher = LSLPublisher(name='IntanEMG', stream_type='EMG',
                         channel_count=64, sample_rate=4000)

while True:
    _, data = device.stream(n_frames=40)
    publisher.push_chunk(data.T)

---

🗂️ Package Structure

intan/
├── io/                     # File loading (.rhd, .dat, .csv, .npz)
├── interface/              # RHX device, LSL, hardware interfaces
├── processing/             # Signal processing and filtering
├── ml/                     # Machine learning pipeline
├── plotting/               # Visualization utilities
├── applications/           # GUI applications
├── decomposition/          # PCA, ICA decomposition
└── samples/                # Sample data utilities

examples/
├── Read_Files/             # File loading examples
├── RHXDevice/              # Device streaming examples
├── LSL/                    # Lab Streaming Layer examples
├── gesture_classifier/     # ML training and prediction
├── applications/           # GUI application demos
├── 3D_printed_arm_control/ # Robotic control integration
└── interface/              # Hardware interfacing examples

---

🎯 Use Cases

📊 Data Analysis

• Load and analyze .rhd recordings
• Batch process multiple files
• Extract specific time segments
• Generate publication-quality figures

🔴 Real-time Applications

• Live EMG visualization
• Online gesture recognition
• Closed-loop control systems
• Synchronized multi-modal recording

🤖 Machine Learning

• Train gesture classifiers
• Real-time prediction
• Cross-session validation
• Transfer learning

🔬 Research

• Impedance testing
• Signal quality monitoring
• Protocol automation
• Custom experimental setups

---

📖 Documentation

Comprehensive documentation is available at neuro-mechatronics-interfaces.github.io/python-intan

Key Sections:

• Installation Guide
• Loading Files
• Real-time Streaming
• Signal Processing
• Gesture Classification
• LSL Integration
• GUI Applications
• Hardware Control
• FAQ
• API Reference

---

🎓 Examples

The examples/ directory contains 60+ working examples organized by category:

# File loading
python examples/Read_Files/load_rhd_demo.py

# Real-time streaming
python examples/RHXDevice/scrolling_live.py

# Gesture classification pipeline
python examples/gesture_classifier/1a_build_training_dataset_rhd.py
python examples/gesture_classifier/2_train_model.py
python examples/gesture_classifier/3d_predict_from_device_realtime.py

# GUI applications
python examples/applications/run_emg_viewer.py
python examples/applications/gesture_pipeline_gui.py

# LSL streaming
python examples/LSL/lsl_waveform_viewer.py
python examples/LSL/lsl_rms_barplot.py

See the Examples Documentation for complete guides.

---

🛠️ Supported Hardware

• Intan RHX Controllers: RHD USB Interface Board, RHD Recording Controller
• Amplifiers: RHD2000 series (RHD2132, RHD2164, RHD2216, etc.)
• Stimulation: RHS2000 series amplifiers
• Peripherals: Raspberry Pi Pico, servo controllers, IMU sensors
• Integration: Lab Streaming Layer (LSL) compatible devices

---

🤝 Contributing

We welcome contributions! Whether it's:

• 🐛 Bug reports
• ✨ Feature requests
• 📝 Documentation improvements
• 🧪 New examples
• 🔧 Code contributions

Please see our Contributing Guide for details.

Ways to contribute:

• Report bugs or request features via GitHub Issues
• Submit pull requests with improvements
• Share your use cases and examples
• Help answer questions in discussions
• Improve documentation

---

📝 Citation

If you use this package in your research, please cite:

@software{Shulgach_Python_Intan_2025,
  author = {Shulgach, Jonathan and Murphy, Max and Foy, Adrian},
  title = {{Python Intan Package}},
  year = {2025},
  month = {01},
  version = {0.0.3},
  url = {https://github.com/Neuro-Mechatronics-Interfaces/python-intan},
  note = {Neuromechatronics Lab, Carnegie Mellon University}
}

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License means:

• ✅ Commercial use
• ✅ Modification
• ✅ Distribution
• ✅ Private use

---

🙏 Acknowledgments

Developed by the Neuromechatronics Lab at Carnegie Mellon University.

Core Contributors:

• Jonathan Shulgach
• Max Murphy
• Adrian Foy

Special Thanks:

• Intan Technologies for hardware and support
• The open-source neuroscience community

---

📧 Contact & Support

• Documentation: neuro-mechatronics-interfaces.github.io/python-intan
• Issues: GitHub Issues
• Email: [e-mail]
• Lab Website: Neuromechatronics Lab

---

🚦 Status & Roadmap

Current Version: 0.0.3 (January 2025)

Completed ✅

• File loading (.rhd, .dat, .csv, .npz)
• Real-time TCP streaming from RHX
• Signal processing pipeline
• Machine learning (CNN, LSTM, Dense models)
• Real-time gesture recognition
• Lab Streaming Layer integration
• GUI applications (EMG viewer, trial selector, gesture pipeline)
• Hardware integration (Pico, robotic arms, IMU)
• Comprehensive documentation and examples

In Progress 🚧

• Performance benchmarking suite
• Extended LSL marker synchronization
• Additional ML model architectures
• Mobile device integration

Planned 📋

• Public training datasets
• Cloud integration for distributed processing
• Advanced impedance testing tools
• Multi-language support (MATLAB, Julia wrappers)

See CHANGELOG.md for detailed version history.

---

⭐ If you find this package useful, please consider giving it a star on GitHub! ⭐

Made with ❤️ by the Neuromechatronics Lab