Harmonic analysis of biosignals#
Important
Like the software? Don’t forget to support it by starring ⭐, sponsoring 💞, or spreading the word 💌
We count on you to help us making it better by contributing even the tiniest improvements (a typo, a rephrasing to make things clearer, a comment to the code, a new option, etc.). Biotuner belongs to you. Make yourself part of the team!
Home#
Welcome to Biotuner’s documentation where you can learn about computational tools derived from music theory and neurophysiology to develop novel ways to analyze, but also use electrophysiological signals as a source of musical or visual composition.
See also
You can find information on how to cite this documentation here.
The documentation covers installation instructions, the API, as well as notebooks that show you how to extract meaningful harmonic information from brain signals, and use the visualization methods of the toolbox. It is for scientists and artists alike.
It is constructed in an open-ended manner to allow for the addition of new methods and tools for extended signal support (e.g. cardiac signals and plant signals).
You can navigate to the different sections using the left panel.
Biotuner
Python toolbox that incorporates tools from biological signal processing and musical theory to extract harmonic structures from biosignals.
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 biotunerFor development: Clone the repo and run
invoke setupTo verify installation: Run
invoke test
Simple use case#
biotuning = biotuner(sf = 1000) #initialize the object
biotuning.peaks_extraction(data, peaks_function='FOOOF') #extract spectral peaks
biotuning.compute_peaks_metrics() #get consonance metrics for spectral peaks
Running the Biotuner GUI#
You can run the Biotuner graphical interface using Invoke or Streamlit.
Option 1: Run via Invoke (Recommended)#
If you have invoke installed and set up, simply run:
invoke gui
This command will ensure all dependencies are installed before launching the GUI.
Option 2: Run via Streamlit#
If you prefer to start the GUI manually, run:
streamlit run gui.py
Note: If you use this option, you must first install the GUI dependencies. You can install them using:
pip install ".[gui]"
Access the Interface#
Once the GUI starts, you should see a local URL in the terminal, such as:
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#
