Complete Phase 4: Release Preparation (Docs, Packaging, Cleanup)

Author: Jshulgach

README.md

@@ -1,48 +1,95 @@
 # Python Open-Ephys
 
-This repository provides a set of tools using the Open-Ephys data acquisition system and GUI for electromyography (EMG) data.
+A comprehensive Python toolkit for working with Open Ephys devices, featuring signal processing, machine learning, and real-time visualization tools. This package seamlessly integrates with the Open Ephys GUI via ZMQ.
 
-<!-- ![intan_logo.png](/assets/intan_logo.png) -->
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
 
+## Features
 
-Code was written and tested using Windows 11, Python 3.10.
-![Python](https://img.shields.io/badge/python-3.10-blue)
-![License](https://img.shields.io/badge/license-MIT-green)
+### 🖥️ Applications (GUI)
+-   **Real-Time EMG Viewer**: Live ZMQ streaming plot with signal quality checks (`channels` loaded dynamically).
+-   **Offline EMG Viewer**: Advanced offline analysis of `.npz` recordings with filtering and spectrograms.
+-   **Trial Selector**: Tool for manual segmentation and labeling of EMG trials.
+
+### 🧠 Machine Learning
+-   **EMGClassifierCNNLSTM**: Hybrid CNN-LSTM model for spatio-temporal gesture recognition.
+-   **Model Manager**: Utilities to save, load, and manage PyTorch models.
+-   **Evaluation**: Metrics and tools for evaluating model performance.
+
+### 📡 Signal Processing
+-   **Channel QC**: Automated signal quality assessment (noise, saturation).
+-   **Synchronization**: Tools to align multi-modal data (e.g., EMG + Motion Capture/Video).
+-   **Filtering**: Real-time and offline filters (Bandpass, Notch, Smoothing).
+-   **Features**: Extract RMS, MAV, Zero Crossings, and IMU features.
 
 ## Installation
 
-1. Create a virtual environment using [Anaconda](https://www.anaconda.com/products/distribution) or Python's virtualenv
-   - Using Anaconda:
-      ~~~
-      conda create -n ephys
-      conda activate ephys
-      ~~~
-   - Using Python's virtualenv:
-     ~~~
-     python3 -m venv .ephys
-     source .ephys/bin/activate # Linux
-     call .ephys/Scripts/activate # Windows
-     ~~~
-2. Clone the repository and navigate to the project directory
-   ~~~
-   git clone https://github.com/Neuro-Mechatronics-Interfaces/Python_Open-Ephys.git
-   cd Python_Open-Ephys
-   ~~~
-3. Install dependencies
-    ~~~
-    pip install -r requirements.txt
-    ~~~
-4. Setup Open-Ephys GUI 
-    - Install from the [Open-Ephys website](https://open-ephys.org/gui) and select your system 
-    - Install the [ZQM Plugin](https://open-ephys.github.io/gui-docs/User-Manual/Plugins/ZMQ-Interface.html) for streaming data
+### From Source
+1.  **Clone the repository**:
+    ```bash
+    git clone https://github.com/Neuro-Mechatronics-Interfaces/python-open-ephys.git
+    cd python-open-ephys
+    ```
+
+2.  **Create a virtual environment** (recommended):
+    ```bash
+    python -m venv .venv
+    # Windows
+    .venv\Scripts\activate
+    # Linux/Mac
+    source .venv/bin/activate
+    ```
+
+3.  **Install dependencies**:
+    ```bash
+    pip install -e .
+    ```
+
+### Dependencies
+-   `numpy`, `scipy`, `matplotlib`, `pandas`
+-   `torch` (for ML models)
+-   `pyqt5`, `pyqtgraph` (for GUIs)
+-   `pyzmq` (for streaming)
+-   `open-ephys-python-tools`
 
 ## Usage
 
-The OpenEphysClient class can be easily imported into your current project. The class provides a simple interface to connect to the Open-Ephys GUI and stream data.
+### 1. Real-Time Viewer
+Launch the real-time plotter to visualize live data from Open Ephys:
+```bash
+python -m pyoephys.applications._realtime_viewer --host 127.0.0.1 --channels 0 1 2 3
+```
+*Note: Ensure the ZMQ Interface plugin is active in Open Ephys GUI.*
+
+### 2. Machine Learning
+Train a CNN-LSTM model for gesture recognition:
+```python
+from pyoephys.ml import EMGClassifierCNNLSTM
+import torch
+
+# Initialize model (4 classes, 8 channels, 200ms window)
+model = EMGClassifierCNNLSTM(num_classes=4, num_channels=8, input_window=200)
+
+# Train (see examples/ml/train_cnn_lstm.py for full loop)
+# model.fit(X_train, y_train)
+```
 
+### 3. Signal Processing
+Check signal quality of your recording:
 ```python
-from open_ephys import OpenEphysClient
-client = OpenEphysClient()
-samples = client.get_samples(channel=8)
+from pyoephys.processing import ChannelQC
+
+qc = ChannelQC(fs=2000)
+results = qc.compute_qc(data_chunk)
+print(results) # Status (Good/Bad) per channel
 ```
-Check the directory for other demo example scripts
+
+## Examples
+Check the `examples/` directory for complete scripts:
+-   `examples/ml/train_cnn_lstm.py`: Train a gesture classifier.
+-   `examples/integration/sync_multimodal_data.py`: Align EMG with 3D hand landmarks.
+-   `examples/processing/run_channel_qc.py`: Run quality control checks.
+
+## License
+MIT License. See [LICENSE](LICENSE) for details.

examples/integration/sync_multimodal_data.py

@@ -0,0 +1,139 @@
+"""
+Multimodal Synchronization Example
+----------------------------------
+Aligns Open Ephys EMG data with Hand Tracking landmarks.
+
+This script demonstrates:
+1. Loading EMG data from an Open Ephys session (or mock data).
+2. Loading Landmark data from a .npz file (captured via udp_landmark_logger.py).
+3. Computing the movement signal from 3D hand landmarks.
+4. Computing the EMG envelope.
+5. Finding the temporal offset to align the two streams.
+
+Usage:
+    python sync_multimodal_data.py --emg <path_to_session> --landmarks landmarks.npz
+"""
+
+import argparse
+import numpy as np
+import matplotlib.pyplot as plt
+from pyoephys.processing import (
+    compute_landmark_movement_signal,
+    compute_emg_envelope_signal,
+    find_sync_offset
+)
+from pyoephys.io import load_open_ephys_session
+
+def create_mock_data(duration=30.0, emg_fs=2000, landmark_fs=30.0, offset_sec=2.5):
+    """Generate aligned mock data if no files provided."""
+    print("Generating mock data...")
+    t_emg = np.arange(0, duration, 1/emg_fs)
+    t_lm = np.arange(0, duration, 1/landmark_fs)
+    
+    # Common activity profile (e.g., 3 bursts)
+    activity = np.zeros_like(t_emg)
+    burst_times = [5.0, 15.0, 25.0]
+    for bt in burst_times:
+        # gaussian burst
+        activity += np.exp(-0.5 * ((t_emg - bt - offset_sec) / 0.5)**2)
+    
+    # EMG = noise modulated by activity
+    emg_data = np.random.randn(8, len(t_emg)) * (1 + 10 * activity)
+    
+    # Landmarks = velocity matches activity
+    # We integrate activity to get position, so derivative (velocity) matches activity
+    # Here we just fake the landmarks array directly
+    n_frames = len(t_lm)
+    landmarks = np.zeros((n_frames, 21, 3))
+    
+    # Add movement at burst times (unshifted time for landmarks, shifted for EMG)
+    # Effectively EMG is delayed by offset_sec relative to ground truth event, or vice versa
+    # Let's say Event happens at t. Landmarks see it at t. EMG sees it at t + offset.
+    
+    # Re-do: 
+    # Event times: 5, 15, 25
+    # Landing on landmarks at: 5, 15, 25
+    # Landing on EMG at: 5+offset, 15+offset, 25+offset
+    
+    # Landmark movement
+    for i, t in enumerate(t_lm):
+        dist = np.min(np.abs(t - np.array(burst_times)))
+        if dist < 1.0:
+            # Move index finger
+            landmarks[i, 8, 1] = np.sin(20 * t) * 0.1
+            
+    return emg_data, t_emg, landmarks, t_lm
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--emg", type=str, help="Path to Open Ephys Session folder")
+    parser.add_argument("--landmarks", type=str, help="Path to landmarks.npz")
+    args = parser.parse_args()
+
+    if args.emg and args.landmarks:
+        # Load Real Data
+        print(f"Loading EMG from {args.emg}...")
+        session = load_open_ephys_session(args.emg)
+        emg_data = session['amplifier_data']
+        emg_fs = session['sample_rate']
+        t_emg = np.arange(emg_data.shape[1]) / emg_fs
+        
+        print(f"Loading Landmarks from {args.landmarks}...")
+        lm_data = np.load(args.landmarks)
+        # (T, Hands, 21, 3) -> take first hand
+        landmarks = lm_data['landmarks'][:, 0, :, :] 
+        t_lm = lm_data['timestamps']
+        # zero-align timestamps for relative processing if needed, 
+        # usually we use "system time" for both, so we keep absolute.
+        
+    else:
+        # Use Mock Data
+        emg_data, t_emg, landmarks, t_lm = create_mock_data()
+        emg_fs = 1.0 / (t_emg[1] - t_emg[0])
+
+    # 1. Process Landmarks -> Movement Signal
+    print("Computing landmark movement signal...")
+    # landmarks shape: (frames, 21, 3)
+    lm_signal, t_lm_clean = compute_landmark_movement_signal(landmarks, t_lm)
+
+    # 2. Process EMG -> Envelope
+    print("Computing EMG envelope...")
+    emg_env, t_emg_env = compute_emg_envelope_signal(emg_data, emg_fs)
+
+    # 3. Find Sync
+    print("Calculating synchronization offset...")
+    # This finds lag such that: emg(t) ~ lm(t + offset)
+    # Positive offset => Landmarks are DELAYED relative to EMG? 
+    # Check docstring: "Positive offset means landmarks are DELAYED relative to EMG."
+    sync_result = find_sync_offset(emg_env, t_emg_env, lm_signal, t_lm_clean)
+    
+    offset = sync_result['offset_sec']
+    conf = sync_result['confidence']
+    print(f"\nFound Offset: {offset:.4f} seconds")
+    print(f"Confidence: {conf:.2f}")
+
+    # 4. Plot
+    plt.figure(figsize=(10, 6))
+    
+    # Normalize for plotting
+    def norm(x): return (x - np.mean(x)) / np.std(x)
+    
+    plt.subplot(2, 1, 1)
+    plt.title("Original Signals")
+    plt.plot(t_emg_env, norm(emg_env), label="EMG Envelope", alpha=0.7)
+    plt.plot(t_lm_clean, norm(lm_signal), label="Landmark Movement", alpha=0.7)
+    plt.legend()
+    plt.grid(True)
+    
+    plt.subplot(2, 1, 2)
+    plt.title(f"Aligned (Landmarks shifted by {-offset:.2f}s)")
+    plt.plot(t_emg_env, norm(emg_env), label="EMG Envelope", alpha=0.7)
+    plt.plot(t_lm_clean - offset, norm(lm_signal), label="Aligned Landmarks", alpha=0.7)
+    plt.legend()
+    plt.grid(True)
+    
+    plt.tight_layout()
+    plt.show()
+
+if __name__ == "__main__":
+    main()

examples/integration/udp_landmark_logger.py

@@ -0,0 +1,117 @@
+"""
+UDP Landmark Logger
+-------------------
+Listens for hand landmarks broadcasted by the Stereo Hand Tracker (port 5005)
+and saves them to a structured .npz file for synchronization with EMG data.
+
+Usage:
+    python udp_landmark_logger.py --output landmarks.npz --duration 30
+"""
+
+import socket
+import json
+import time
+import argparse
+import numpy as np
+import signal
+
+def main():
+    parser = argparse.ArgumentParser(description="Log UDP landmarks to NPZ")
+    parser.add_argument("--port", type=int, default=5005, help="UDP port (default: 5005)")
+    parser.add_argument("--output", type=str, default="landmarks.npz", help="Output filename")
+    parser.add_argument("--duration", type=float, default=60.0, help="Recording duration in seconds")
+    args = parser.parse_args()
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.bind(("0.0.0.0", args.port))
+    sock.settimeout(1.0)
+
+    print(f"Listening on port {args.port}...")
+    print(f"Recording to {args.output} for {args.duration} seconds...")
+    print("Press Ctrl+C to stop early.")
+
+    timestamps = []
+    frames = []
+    # Store landmarks as list of (N_hands, 21, 3) arrays
+    # Since N_hands can vary, we might just store flat lists and post-process
+    landmark_history = [] 
+
+    start_time = time.time()
+    packet_count = 0
+
+    try:
+        while True:
+            elapsed = time.time() - start_time
+            if elapsed >= args.duration:
+                break
+            
+            try:
+                data, addr = sock.recvfrom(65535)
+                packet = json.loads(data.decode("utf-8"))
+                
+                # Packet format: {'timestamp': float, 'hands': [{'hand_index': i, 'landmarks': [[x,y,z],...]}, ...], ...}
+                
+                # Use local receive time for strict sync, or packet timestamp if reliable?
+                # Usually best to trust packet timestamp if source clock is good, or mix.
+                # Here we'll use packet timestamp if available, else local.
+                ts = packet.get("timestamp", time.time())
+                
+                hands_list = packet.get("hands", [])
+                
+                # Sort hands by index to maximize consistency
+                hands_list.sort(key=lambda h: h.get("hand_index", 0))
+                
+                # Extract landmarks: (N_hands, 21, 3)
+                current_frame_landmarks = []
+                for h in hands_list:
+                    lm = np.array(h["landmarks"]) # (21, 3)
+                    current_frame_landmarks.append(lm)
+                
+                if current_frame_landmarks:
+                    # For simple storage, lets just store the first hand, or all if consistent?
+                    # To be robust, let's keep it flexible: store list of objects
+                    landmark_history.append(current_frame_landmarks)
+                    timestamps.append(ts)
+                    frames.append(packet.get("frame", packet_count))
+                    packet_count += 1
+                    
+                if packet_count % 100 == 0:
+                    print(f"\rCaptured {packet_count} frames ({elapsed:.1f}s)", end="")
+                    
+            except socket.timeout:
+                continue
+            except KeyboardInterrupt:
+                break
+                
+    except KeyboardInterrupt:
+        print("\nStopping...")
+
+    print(f"\nSaving {len(timestamps)} frames to {args.output}")
+    
+    # Post-process: Pad to max hands to make a dense array? 
+    # Or just pickle the list. NPZ supports object arrays.
+    # Let's try to make a dense array (T, MaxHands, 21, 3)
+    if not landmark_history:
+        print("No data captured.")
+        return
+
+    max_hands = max(len(h) for h in landmark_history)
+    T = len(timestamps)
+    dense_landmarks = np.zeros((T, max_hands, 21, 3), dtype=np.float32)
+    
+    for t, hands in enumerate(landmark_history):
+        for h_i, hand_lm in enumerate(hands):
+            if h_i < max_hands:
+                dense_landmarks[t, h_i] = hand_lm
+
+    np.savez_compressed(
+        args.output,
+        timestamps=np.array(timestamps),
+        frames=np.array(frames),
+        landmarks=dense_landmarks, # (T, Hands, 21, 3)
+        fs_estimated=T/args.duration
+    )
+    print("Done.")
+
+if __name__ == "__main__":
+    main()