Final polish: README, documentation, and interface standardization

Author: Jshulgach

README.md

@@ -1,136 +1,103 @@
 # Python OEphys
 
-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.
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://badge.fury.io/py/python-oephys.svg)](https://badge.fury.io/py/python-oephys)
 
-![Python](https://img.shields.io/badge/python-3.10%2B-blue)
-![License](https://img.shields.io/badge/license-MIT-green)
+**python-oephys** is a comprehensive Python toolkit for working with Open Ephys devices and electrophysiology data. From file loading to real-time ZMQ streaming, signal processing to machine learning, and visualization tools—everything you need for high-density neural data analysis in one package.
 
-## Features
+---
 
-### 🖥️ 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.
+## ✨ Key Features
 
-### 🧠 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.
+- 📁 **File I/O**: Robust support for Open Ephys Binary (`.oebin`) and `.npz` formats
+- 🔴 **Real-time Streaming**: Seamless integration with the Open Ephys GUI via ZMQ
+- 🎛️ **Signal Processing**: Filtering (Bandpass, Notch), Channel QC, and synchronization
+- 🤖 **Machine Learning**: Hybrid CNN-LSTM models for real-time gesture recognition
+- 📊 **Visualization**: Real-time EMG viewer, offline analysis, and trial segmentation tools
+- 🚀 **Performance**: Optimized for low-latency real-time applications
 
-### 📡 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.
+---
 
-### 💾 Data & IO
--   **Unified IO**: Robust support for Open Ephys Binary (`.oebin`) and `.npz` formats.
--   **Dataset Builder**: Advanced tools to discover, group, and merge multi-session datasets.
--   **Spatial Mapping**: Grid reorientation tools (`rot90`, `flipH`, etc.) for high-density arrays.
+## 📦 Installation
 
-## Installation
+### From TestPyPI (Current Development Release)
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --no-deps python-oephys
+```
 
 ### 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
-
-### 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
+git clone https://github.com/Neuro-Mechatronics-Interfaces/python-open-ephys.git
+cd python-open-ephys
+pip install -e .
 ```
-*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
+### Optional Extras
 
-# Initialize model (4 classes, 8 channels, 200ms window)
-model = EMGClassifierCNNLSTM(num_classes=4, num_channels=8, input_window=200)
+- **GUI**: `pip install 'python-oephys[gui]'` (PyQt5, pyqtgraph)
+- **ML**: `pip install 'python-oephys[ml]'` (PyTorch, scikit-learn)
+- **Docs**: `pip install 'python-oephys[docs]'` (Sphinx)
 
-# Train (see examples/ml/train_cnn_lstm.py for full loop)
-# model.fit(X_train, y_train)
-```
+---
+
+## 🚀 Getting Started
+
+### Load and Filter Data
 
-### 3. Signal Processing
-Check signal quality of your recording:
 ```python
-from pyoephys.processing import ChannelQC
+from pyoephys.io import load_open_ephys_session
+from pyoephys.processing import filter_emg
 
-qc = ChannelQC(fs=2000)
-results = qc.compute_qc(data_chunk)
-print(results) # Status (Good/Bad) per channel
+# Load session
+sess = load_open_ephys_session('path/to/recording.oebin')
+data = sess['amplifier_data']
+fs = sess['sample_rate']
+
+# Apply filters
+filtered = filter_emg(data, filter_type='bandpass', lowcut=10, highcut=500, fs=fs)
 ```
 
-### 4. Unified CLI Tools
-Build a dataset from multiple sessions and train/predict with a single command workflow:
-```bash
-# 1. Build Dataset (Auto-discovery, Preprocessing, Merging)
-python examples/gesture_classifier/1_build_dataset.py --root_dir ./data --multi_file --paper_style
+### Real-time ZMQ Streaming
 
-# 2. Train Model
-python examples/gesture_classifier/2_train_model.py --root_dir ./data --label my_model
+```bash
+# Launch the live viewer (ensure ZMQ Interface plugin is active in GUI)
+python -m pyoephys.applications._realtime_viewer --host 127.0.0.1 --channels 0:8
+```
 
-# 3. Predict (Offline or Real-time Stream)
-python examples/gesture_classifier/predict.py stream --root_dir ./data --label my_model
+---
+
+## 🗂️ Package Structure
+
+```text
+pyoephys/
+├── applications/     # GUI applications (Real-time & Offline viewers)
+├── interface/        # ZMQ, LSL, and playback clients
+├── io/               # Unified file loaders (.oebin, .npz)
+├── ml/               # Gesture classification (CNN-LSTM)
+├── plotting/         # Visualization utilities
+└── processing/       # Signal filters, QC, and synchronization
+
+examples/
+├── benchmarks/       # Throughput and latency tests
+├── interface/        # LSL, ZMQ, and hardware control
+│   ├── hardware/     # Serial/UDP Pico integration
+│   ├── imu/          # Sleeve IMU client & monitor
+│   ├── lsl/          # LSL streaming & capture
+│   └── zmq/          # ZMQ clients & plotters
+└── machine_learning/ # Model training and evaluation
 ```
 
-## Examples
-Check the `examples/` directory for complete scripts:
--   `examples/gesture_classifier/2_train_model.py`: Train a gesture classifier.
--   `examples/synchronization/sync_multimodal_data.py`: Align EMG with 3D hand landmarks.
--   `examples/analysis/run_channel_qc.py`: Run quality control checks.
--   `examples/interface/zmq/zmq_client.py`: Real-time ZMQ client example.
--   `examples/read_files/example_load_oebin_file.py`: Load Open Ephys data.
-
-## License
-MIT License. See [LICENSE](LICENSE) for details.
-
-## Development & Release
-
-### Versioning
-This project uses **dynamic versioning** via `setuptools_scm`. The version is automatically derived from Git tags.
-
-### How to Release
-1.  **Commit** all changes.
-2.  **Tag** the commit with the new version number:
-    ```bash
-    git tag -a v0.1.0 -m "Release v0.1.0"
-    ```
-3.  **Push** the tag to GitHub:
-    ```bash
-    git push origin v0.1.0
-    ```
-4.  **Create a Release** on GitHub:
-    - Go to **Releases** > **Draft a new release**.
-    - Select the tag `v0.1.0`.
-    - Click **Publish release**.
-5.  The `publish.yml` workflow will trigger, build the package, and upload to PyPI.
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+<p align="center">
+  Made with ❤️ by the Neuromechatronics Lab
+</p>

docs/source/conf.py

@@ -4,10 +4,11 @@
 import sys
 sys.path.insert(0, os.path.abspath('../../src'))
 
+import pyoephys
 project = 'python-oephys'
 copyright = '2025, Jonathan Shulgach'
 author = 'Jonathan Shulgach'
-release = '0.0.1'
+release = pyoephys.__version__
 
 extensions = [
     'sphinx.ext.autodoc',

pyproject.toml

@@ -37,6 +37,7 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools_scm]
 write_to = "src/pyoephys/_version.py"
+local_scheme = "no-local-version"
 
 [tool.setuptools]
 package-dir = {"" = "src"}

src/pyoephys/_version.py

@@ -28,7 +28,7 @@
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.1.dev14+g35ff9ad53.d20260126'
-__version_tuple__ = version_tuple = (0, 1, 'dev14', 'g35ff9ad53.d20260126')
+__version__ = version = '0.1.1.dev0'
+__version_tuple__ = version_tuple = (0, 1, 1, 'dev0')
 
-__commit_id__ = commit_id = 'g35ff9ad53'
+__commit_id__ = commit_id = 'gd2999118a'

src/pyoephys/interface/__init__.py

@@ -1,3 +1,6 @@
+"""
+Hardware interfaces for ZMQ, LSL, and Open Ephys GUI.
+"""
 from ._gui_client import GUIClient
 from ._gui_events import Event, Spike
 from ._device import OpenEphysDevice

src/pyoephys/io/__init__.py

@@ -1,3 +1,6 @@
+"""
+Input and Output (IO) utilities for Open Ephys and NPZ data.
+"""
 from ._session_loader import load_open_ephys_session
 from ._file_utils import (
     find_oebin_files,

src/pyoephys/ml/__init__.py

@@ -1,3 +1,6 @@
+"""
+Machine Learning models and utilities for gesture classification.
+"""
 from ._models import (
     EMGRegressor,
     EMGClassifier,

src/pyoephys/processing/__init__.py

@@ -1,3 +1,6 @@
+"""
+Signal processing, filtering, and feature extraction.
+"""
 from ._metrics_utils import load_metrics_data, get_metrics_file
 from ._filters import (
     bandpass_filter,