biotuner


Namebiotuner JSON
Version 0.0.18 PyPI version JSON
download
home_pageNone
SummaryTime series harmonic analysis for adaptive tuning systems and microtonal exploration
upload_time2025-07-10 22:33:21
maintainerNone
docs_urlNone
authorNone
requires_python>=3.6
licenseMIT
keywords biosignal harmony tuning eeg microtonality music time series
VCS
bugtrack_url
requirements matplotlib seaborn mne fooof emd contfrac scipy numpy mido sympy pytest
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <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>

<!-- 🧬![Biotuner](https://img.shields.io/badge/Biotuner-Documentation-blue?style=for-the-badge&logo=bookstack) 🎹 -->


# **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.

![image](https://github.com/user-attachments/assets/5566dea7-378c-4621-9ec8-7e2ef6991c57)

## 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>

![Biotuner_pipeline (6)-page-001](https://user-images.githubusercontent.com/49297774/153693263-90c1e49e-a8c0-4a93-8219-491d1ede32e1.jpg)

## Peaks extraction methods

![biotuner_peaks_extraction](https://user-images.githubusercontent.com/49297774/156813349-ddcd40d0-57c9-41f2-b62a-7cbb4213e515.jpg)


            

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![Biotuner](https://img.shields.io/badge/Biotuner-Documentation-blue?style=for-the-badge&logo=bookstack) \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![image](https://github.com/user-attachments/assets/5566dea7-378c-4621-9ec8-7e2ef6991c57)\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![Biotuner_pipeline (6)-page-001](https://user-images.githubusercontent.com/49297774/153693263-90c1e49e-a8c0-4a93-8219-491d1ede32e1.jpg)\n\n## Peaks extraction methods\n\n![biotuner_peaks_extraction](https://user-images.githubusercontent.com/49297774/156813349-ddcd40d0-57c9-41f2-b62a-7cbb4213e515.jpg)\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"
}
        
Elapsed time: 1.32765s