Biotuner

Python toolbox that incorporates tools from biological signal processing and musical theory to extract harmonic structures from biosignals.

✨ Features

• 🎵 Harmonic Analysis: Extract harmonic structures from biosignals using music theory principles
• 📊 Multiple Peak Detection Methods: FOOOF, EMD, fixed-frequency, and harmonic-recurrence based methods
• 🧮 Harmonicity Metrics: Compute consonance, dissonance, harmonic similarity, Tenney height, and more
• 🎹 Musical Applications: Generate musical scales, tuning systems, and MIDI output from biosignals
• 🔬 Group Analysis (BETA): Batch processing for multiple time series with automatic aggregation
• 📈 Rich Visualizations: Publication-ready plots for spectral analysis and harmonic relationships
• 🧠 Multi-modal Support: Compatible with EEG, ECG, EMG, plant signals, and other biosignals
• 🎨 Interactive GUI: Graphical interface for easy exploration

Installation

1. Install using PyPI (Recommended)

To install the latest stable version of Biotuner from PyPI, run:

pip install biotuner

---

2. Install from the GitHub Repository (Development Version)

If you want the latest development version or contribute to the code, follow these steps:

2.1. Automatically Setup the Environment (Recommended)

The easiest way to set up a development environment is by using invoke, which will:

✅ Create a Conda environment
✅ Install dependencies
✅ Install Biotuner in editable mode

# Clone the repository
git clone https://github.com/AntoineBellemare/biotuner.git
cd biotuner

# Install Invoke (if not already installed)
pip install invoke

# Automatically create a Conda environment and install Biotuner
invoke setup

👉 This will create a Conda environment named biotuner_env and install all dependencies.

To activate the Conda environment manually:

conda activate biotuner_env

---

2.2. Manual Setup (Alternative)

If you prefer to set up the environment manually, follow these steps:

1️⃣ Create a Conda environment

conda create --name biotuner_env python=3.11 -y
conda activate biotuner_env

2️⃣ Install dependencies

pip install -r requirements.txt
pip install -e .

---

3. Verify Installation by Running Tests

To confirm that Biotuner is installed correctly, run the test suite:

invoke test

or manually using:

pytest tests/

If all tests pass ✅, your installation is complete!

---

🎯 Summary

• For general users: Install via pip install biotuner
• For development: Clone the repo and run invoke setup
• To verify installation: Run invoke test

Simple use case

Single Time Series Analysis

from biotuner import compute_biotuner

# Initialize the object
biotuning = compute_biotuner(sf=1000)

# Extract spectral peaks
biotuning.peaks_extraction(data, peaks_function='FOOOF')

# Get consonance metrics for spectral peaks
biotuning.compute_peaks_metrics()

Group Analysis (🧪 BETA)

Analyze multiple time series simultaneously with automatic aggregation and group comparisons:

from biotuner import BiotunerGroup
import numpy as np

# Multiple trials or electrodes: shape (n_series, n_samples)
data = np.random.randn(10, 5000)

# Create group object
btg = BiotunerGroup(data, sf=1000, axis_labels=['trials'])

# Run analysis pipeline
btg.compute_peaks(peaks_function='FOOOF', min_freq=1, max_freq=50)
btg.compute_metrics(n_harm=10)

# Get summary statistics
summary = btg.summary()

Note: The BiotunerGroup module is currently in beta. The API may change in future releases.

---

🌐 Biotuner Engine - Web Interface

Explore Biotuner's capabilities through our interactive web interface:

biotuner-engine.kairos-hive.org

The Biotuner Engine provides a user-friendly web application to analyze biosignals, visualize harmonic structures, and explore musical applications directly in your browser—no installation required!

---

Multimodal Harmonic Analysis

The figure above illustrates Biotuner's ability to extract harmonic structures across different biological and physical systems. It showcases harmonic ratios detected in biosignals from the brain, heart, and plants, as well as their correspondence with audio signals. By analyzing the fundamental frequency relationships in these diverse modalities, Biotuner enables a cross-domain exploration of resonance and tuning in biological and artificial systems.

Peaks extraction methods

---

📚 Documentation & Resources

• Full Documentation - Complete API reference and tutorials
• Getting Started Guide - Step-by-step introduction
• API Reference - Detailed function and class documentation
  • BiotunerObject - Single time series analysis
  • BiotunerGroup (BETA) - Group analysis
  • Metrics - Harmonicity metrics
  • Peak Extraction - Peak detection methods
• Examples & Notebooks - Jupyter notebook tutorials

🤝 Contributing

We welcome contributions! Whether it's:

• 🐛 Bug reports
• 💡 Feature requests
• 📝 Documentation improvements
• 🔧 Code contributions

Please feel free to open an issue or submit a pull request on GitHub.

📄 License

Biotuner is licensed under the MIT License.

📖 Citation

If you use Biotuner in your research, please cite our work. See the citation guide for more information.

💬 Support

• Issues: GitHub Issues
• Email: antoine.bellemare9@gmail.com
• Documentation: https://antoinebellemare.github.io/biotuner/

---

Made with ❤️ by the Biotuner development team