<p align="center">
<img src="https://github.com/AntoineBellemare/biotuner/assets/49297774/fc83d888-db2a-4f9f-ba26-65a58c42b72d" alt="biotuner_logo" width="200"/>
</p>
<h1 align="center">Biotuner</h1>
<h3 align="center"> Python toolbox that incorporates tools from biological signal processing and musical theory to extract harmonic structures from biosignals. </h3>
<p align="center">
<a href="https://github.com/AntoineBellemare/biotuner/actions/workflows/ci.yml">
<img alt="Tests" src="https://github.com/AntoineBellemare/biotuner/actions/workflows/python-test.yml/badge.svg">
</a>
<a href="https://codecov.io/github/AntoineBellemare/biotuner">
<img alt="Codecov" src="https://codecov.io/github/AntoineBellemare/biotuner/branch/main/graph/badge.svg?token=DW8JS03EV9">
</a>
<a href="https://pypi.org/project/biotuner/">
<img alt="PyPI" src="https://img.shields.io/pypi/v/biotuner">
</a>
<a href="https://antoinebellemare.github.io/biotuner/">
<img alt="Biotuner Docs" src="https://img.shields.io/website?label=Docs&up_color=blue&url=https%3A%2F%2Fantoinebellemare.github.io%2Fbiotuner%2F">
</a>
<a href="https://github.com/AntoineBellemare/biotuner/blob/main/LICENSE">
<img alt="License" src="https://img.shields.io/github/license/AntoineBellemare/biotuner">
</a>
<a href="https://github.com/AntoineBellemare/biotuner/stargazers">
<img alt="GitHub stars" src="https://img.shields.io/github/stars/AntoineBellemare/biotuner?style=social">
</a>
<a href="https://pypi.org/project/biotuner/">
<img alt="Python Versions" src="https://img.shields.io/pypi/pyversions/biotuner">
</a>
</p>
<!-- 🧬 🎹 -->
# **Installation**
## **1. Install using PyPI (Recommended)**
To install the latest stable version of **Biotuner** from PyPI, run:
```bash
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**
```bash
# 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:
```bash
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**
```bash
conda create --name biotuner_env python=3.11 -y
conda activate biotuner_env
```
#### **2️⃣ Install dependencies**
```bash
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:
```bash
invoke test
```
or manually using:
```bash
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
```python
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:
```sh
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:
```sh
streamlit run gui.py
```
> **Note:** If you use this option, you must first install the GUI dependencies. You can install them using:
```sh
pip install ".[gui]"
```
### Access the Interface
Once the GUI starts, you should see a local URL in the terminal, such as:
[http://localhost:8501/](http://localhost:8501/)
<div align="center" style="width: 50%; margin: auto; text-align: center;">
<h1 align="center">Multimodal Harmonic Analysis</h1>
<p>
<img src="https://github.com/user-attachments/assets/7e99e0ec-a1da-44f2-8ad9-bdfce8f4a36f" alt="biotuner_multimodal_02" width="50%">
</p>
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.
</div>
## Peaks extraction methods
Raw data
{
"_id": null,
"home_page": null,
"name": "biotuner",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "biosignal, harmony, tuning, eeg, microtonality, music, time series",
"author": null,
"author_email": "Antoine Bellemare <antoine.bellemare9@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b5/da/99d03dc977d0659cb1c23b08639408769fddbc68cb3be79940db031a7e27/biotuner-0.0.18.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://github.com/AntoineBellemare/biotuner/assets/49297774/fc83d888-db2a-4f9f-ba26-65a58c42b72d\" alt=\"biotuner_logo\" width=\"200\"/>\n</p>\n\n<h1 align=\"center\">Biotuner</h1>\n<h3 align=\"center\"> Python toolbox that incorporates tools from biological signal processing and musical theory to extract harmonic structures from biosignals. </h3>\n\n<p align=\"center\">\n <a href=\"https://github.com/AntoineBellemare/biotuner/actions/workflows/ci.yml\">\n <img alt=\"Tests\" src=\"https://github.com/AntoineBellemare/biotuner/actions/workflows/python-test.yml/badge.svg\">\n </a>\n\n <a href=\"https://codecov.io/github/AntoineBellemare/biotuner\">\n <img alt=\"Codecov\" src=\"https://codecov.io/github/AntoineBellemare/biotuner/branch/main/graph/badge.svg?token=DW8JS03EV9\">\n </a>\n\n <a href=\"https://pypi.org/project/biotuner/\">\n <img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/biotuner\">\n </a>\n \n <a href=\"https://antoinebellemare.github.io/biotuner/\">\n <img alt=\"Biotuner Docs\" src=\"https://img.shields.io/website?label=Docs&up_color=blue&url=https%3A%2F%2Fantoinebellemare.github.io%2Fbiotuner%2F\">\n</a>\n\n \n <a href=\"https://github.com/AntoineBellemare/biotuner/blob/main/LICENSE\">\n <img alt=\"License\" src=\"https://img.shields.io/github/license/AntoineBellemare/biotuner\">\n </a>\n \n <a href=\"https://github.com/AntoineBellemare/biotuner/stargazers\">\n <img alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/AntoineBellemare/biotuner?style=social\">\n </a>\n\n <a href=\"https://pypi.org/project/biotuner/\">\n <img alt=\"Python Versions\" src=\"https://img.shields.io/pypi/pyversions/biotuner\">\n </a>\n\n \n</p>\n\n<!-- \ud83e\uddec \ud83c\udfb9 -->\n\n\n# **Installation**\n\n## **1. Install using PyPI (Recommended)**\nTo install the latest stable version of **Biotuner** from PyPI, run:\n```bash\npip install biotuner\n```\n\n---\n\n## **2. Install from the GitHub Repository (Development Version)**\nIf you want the latest development version or contribute to the code, follow these steps:\n\n### **2.1. Automatically Setup the Environment (Recommended)**\nThe easiest way to set up a development environment is by using `invoke`, which will:\n\n\u2705 Create a **Conda environment** \n\u2705 Install **dependencies** \n\u2705 Install **Biotuner in editable mode** \n\n```bash\n# Clone the repository\ngit clone https://github.com/AntoineBellemare/biotuner.git\ncd biotuner\n\n# Install Invoke (if not already installed)\npip install invoke\n\n# Automatically create a Conda environment and install Biotuner\ninvoke setup\n```\n\ud83d\udc49 This will create a Conda environment named `biotuner_env` and install all dependencies.\n\nTo activate the Conda environment manually:\n```bash\nconda activate biotuner_env\n```\n\n---\n\n### **2.2. Manual Setup (Alternative)**\nIf you prefer to set up the environment manually, follow these steps:\n\n#### **1\ufe0f\u20e3 Create a Conda environment**\n```bash\nconda create --name biotuner_env python=3.11 -y\nconda activate biotuner_env\n```\n\n#### **2\ufe0f\u20e3 Install dependencies**\n```bash\npip install -r requirements.txt\npip install -e .\n```\n\n---\n\n## **3. Verify Installation by Running Tests**\nTo confirm that Biotuner is installed correctly, run the test suite:\n```bash\ninvoke test\n```\nor manually using:\n```bash\npytest tests/\n```\nIf all tests pass \u2705, your installation is complete!\n\n---\n\n### **\ud83c\udfaf Summary**\n- **For general users**: Install via `pip install biotuner`\n- **For development**: Clone the repo and run `invoke setup`\n- **To verify installation**: Run `invoke test`\n\n# Simple use case\n\n```python\nbiotuning = biotuner(sf = 1000) #initialize the object\nbiotuning.peaks_extraction(data, peaks_function='FOOOF') #extract spectral peaks\nbiotuning.compute_peaks_metrics() #get consonance metrics for spectral peaks\n\n```\n# Running the Biotuner GUI\n\nYou can run the Biotuner graphical interface using **Invoke** or **Streamlit**.\n\n## Option 1: Run via Invoke (Recommended)\n\nIf you have `invoke` installed and set up, simply run:\n\n```sh\ninvoke gui\n```\nThis command will ensure all dependencies are installed before launching the GUI.\n\n\n\n## Option 2: Run via Streamlit\n\nIf you prefer to start the GUI manually, run:\n\n```sh\nstreamlit run gui.py\n```\n\n> **Note:** If you use this option, you must first install the GUI dependencies. You can install them using:\n\n```sh\npip install \".[gui]\"\n```\n\n### Access the Interface\n\nOnce the GUI starts, you should see a local URL in the terminal, such as:\n\n[http://localhost:8501/](http://localhost:8501/)\n\n<div align=\"center\" style=\"width: 50%; margin: auto; text-align: center;\">\n\n<h1 align=\"center\">Multimodal Harmonic Analysis</h1>\n\n <p>\n <img src=\"https://github.com/user-attachments/assets/7e99e0ec-a1da-44f2-8ad9-bdfce8f4a36f\" alt=\"biotuner_multimodal_02\" width=\"50%\">\n </p>\n\nThe 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.\n\n</div>\n\n\n\n## Peaks extraction methods\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Time series harmonic analysis for adaptive tuning systems and microtonal exploration",
"version": "0.0.18",
"project_urls": {
"Homepage": "https://github.com/antoinebellemare/biotuner"
},
"split_keywords": [
"biosignal",
" harmony",
" tuning",
" eeg",
" microtonality",
" music",
" time series"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "de54ff2cd420ae140bc3c49ea12db9a2c11d104d967df6010ffce4bc04b30229",
"md5": "68d84dfccc1d8e3c8099802b7bc0caa3",
"sha256": "9f8a364298fd4e27c8dcab0a77c4847e8688c84e3a8fa4bda09529b76034d78c"
},
"downloads": -1,
"filename": "biotuner-0.0.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "68d84dfccc1d8e3c8099802b7bc0caa3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 146064,
"upload_time": "2025-07-10T22:33:19",
"upload_time_iso_8601": "2025-07-10T22:33:19.948609Z",
"url": "https://files.pythonhosted.org/packages/de/54/ff2cd420ae140bc3c49ea12db9a2c11d104d967df6010ffce4bc04b30229/biotuner-0.0.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b5da99d03dc977d0659cb1c23b08639408769fddbc68cb3be79940db031a7e27",
"md5": "ef5c0177ea5e1b8410eea688c1677a7f",
"sha256": "181d0fa67b898a6960ed7ada6f763afc63b9948a8614832554c8ef6b19c547c3"
},
"downloads": -1,
"filename": "biotuner-0.0.18.tar.gz",
"has_sig": false,
"md5_digest": "ef5c0177ea5e1b8410eea688c1677a7f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 151896,
"upload_time": "2025-07-10T22:33:21",
"upload_time_iso_8601": "2025-07-10T22:33:21.261293Z",
"url": "https://files.pythonhosted.org/packages/b5/da/99d03dc977d0659cb1c23b08639408769fddbc68cb3be79940db031a7e27/biotuner-0.0.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 22:33:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "antoinebellemare",
"github_project": "biotuner",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.3"
]
]
},
{
"name": "seaborn",
"specs": [
[
">=",
"0.12.1"
]
]
},
{
"name": "mne",
"specs": [
[
">=",
"1.4.0"
]
]
},
{
"name": "fooof",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "emd",
"specs": [
[
">=",
"0.5.5"
]
]
},
{
"name": "contfrac",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.7.3"
]
]
},
{
"name": "numpy",
"specs": [
[
"<",
"2.0"
],
[
">=",
"1.21.4"
]
]
},
{
"name": "mido",
"specs": [
[
">=",
"1.2.10"
]
]
},
{
"name": "sympy",
"specs": [
[
">=",
"1.12"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
}
],
"lcname": "biotuner"
}
JSON
