Harmonic analysis of biosignals

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_logo

Biotuner

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

Tests Codecov PyPI Biotuner Docs License GitHub stars Python Versions

✨ 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

  • 🔷 Harmonic Geometry (BETA): Lift any chord / spectrum into 2-D & 3-D geometric structures — Lissajous curves, Chladni acoustic plates, Stern-Brocot trees, IFS attractors, torus knots, harmonic point clouds — with a per-method metrics layer for quantitative analysis

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

2. Install from the GitHub Repository (Development Version)#

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

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.

🔷 Harmonic Geometry (🧪 BETA)#

biotuner.harmonic_geometry lifts any harmonic content (a chord, a spectral peak set, an EEG window) into structured 2-D and 3-D geometry, plus a per-method metrics layer for quantitative analysis. Useful for visual exploration, scientific comparison across chords / signals, and animation of time-resolved harmonic transitions.

What’s inside (each generator emits a typed GeometryData):

Family

Generators

2-D curves

lissajous_2d / 3d / compound / phase_drift / pairwise_grid, lissajous_topology

Damped trajectories

harmonograph_lateral / rotary / 3d, harmonograph_from_peaks

Polygons & circular

star_polygon, times_table_circle, times_table_from_input, tuning_circle, rose_curve, epicycloid, hypocycloid, interval_vector_diagram, polygon_chord_pattern, consonance_polygon

Acoustic plates

chladni_field_rectangular / circular / polygon / 3d_box, chladni_from_input, chladni_nodal_lines / surfaces

Fractal & number-theoretic

stern_brocot_tree, continued_fraction_rectangles, farey_sequence_layout (circle / line / ford), subharmonic_tree (depth + polar layouts), ifs_harmonic

Generative

lsystem_from_ratios, recursive_polygon, self_similar_tuning, geometry_sequence

3-D geometry

lissajous_tube, harmonic_knot (T(p,q) from chord ratios), harmonic_surface, lsystem_3d, recursive_polyhedron (per-face bump + apex twist), harmonic_point_cloud (5 surfaces incl. Klein, hyperbolic, MOS)

 
from biotuner.harmonic_geometry import (
    HarmonicInput, harmonic_knot, geometry_metrics, plotting,
)

# Bridge from biotuner peaks into the geometry layer
inp = HarmonicInput(ratios=[1, 5/4, 3/2, 7/4])     # Dom7 chord
g   = harmonic_knot(inp)                            # T(p, q) torus knot
print(geometry_metrics(g))                          # winding_p, winding_q, n_vertices, …
plotting.plot_geometry(g)

Metrics monitoring: every generator sets metadata['kind']; geometry_metrics(g) dispatches to one of 37 per-method extractors that yield method-specific scalars on top of the generic structural stats. Trajectories over HarmonicSequence (e.g. windowed biotuner output) come via sequence_metrics(seq, generator, **kw), with radar / line-plot helpers in plotting. Append-only MetricsLog exports CSV / JSON for downstream stats.

from biotuner.harmonic_geometry import MetricsLog
log = MetricsLog()
for chord_name, ratios in chord_table.items():
    log.log_geometry(harmonic_knot(HarmonicInput(ratios=ratios)),
                     label=chord_name)
log.to_csv("knot_metrics.csv")

Note: The harmonic_geometry module is currently in beta. The API surface (37 generators) is stable but optional dependencies (scikit-image for nodal extraction; Pillow for image embedding) are not yet declared as a [project.optional-dependencies] group.

🌐 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

biotuner_multimodal_02

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.

Biotuner_pipeline (6)-page-001

Peaks extraction methods#

biotuner_peaks_extraction

🧭 Package Architecture#

The biotuner package is organized by kind — stateful pipeline classes first, then subpackages, then pure-function modules, then reference data. Each module declares its kind in its docstring header (Module type: Functions / Object / Objects / Data / Subpackage), so the same information is also visible from the source.

Objects (stateful pipeline classes)#

Module

What it does

biotuner_object

compute_biotuner — the main pipeline class: peaks, ratios, scales, metrics, PAC, IMFs, FOOOF, rhythm

biotuner_group

BiotunerGroup — multi-trial / multi-channel runs with aggregation

harmonic_connectivity

PAC, CFC, intermodulation pipeline across channels / bands

transitional_harmony

Time-resolved harmonic-state transitions across signal chunks

harmonic_sequence

Markov / DMD / topology / grammar / Wasserstein / latent-space models of harmonic evolution

Subpackages#

Module

What it does

harmonic_geometry/

Lissajous, Chladni, harmonograph, polygon/circular, fractal, 3D point clouds & surfaces — each as a submodule

Functions#

Module

What it does

peaks_extraction

Welch / FOOOF / EMD / Hilbert-Huang / cepstrum, plus PAC frequencies, polycoherence, intermodulation

peaks_extension

Extend a peak set with harmonics / consonant fits

scale_construction

Sethares dissonance curve, harmonic entropy, Euler-Fokker, harmonic tunings

rhythm_construction

Euclidean / discrete & continuous polyrhythms / second-order / evolution / MIDI / OSC

metrics

Tenney height, Euler gradus, dyad similarity, harmonic similarity, subharmonic tension

harmonic_spectrum

Harmonicity / resonance / phase fields from PSDs

biocolors

Map biosignal frequencies to visible-light wavelengths and RGB

bioelements

Match biosignal peaks to atomic spectral lines (H, O, N, …)

biotuner_mne

MNE-Python integration entry point

stats

Group-level tests on biotuner metrics

surrogates

Surrogate-data generation and comparison

vizs

Dissonance curves, sidebands, scales, demos

plot_utils

Unified plotting helpers (consistent styling across analyses)

plot_config

Color schemes and styles for biotuner plots

harmonic_sequence_viz

Plots for harmonic_sequence outputs

biotuner_utils

Signal generation, .scl writer, MIDI helpers, ratio math

Data#

Module

What it does

dictionaries

Rhythm pattern names, interval names

Reading the table:

  • Object / Objects — module’s primary API is one or more classes; instantiate, then call methods.

  • Subpackage — folder with its own submodules; see its __init__.py for the public surface.

  • Functions — module is a flat collection of pure functions; import what you need.

  • Data — module exposes data tables (dicts, constants); import and read.

The kind tag also lives at the top of every module file:

"""biotuner.peaks_extraction — extract spectral peaks from biosignals.

Module type: Functions
...
"""

so help(biotuner.peaks_extraction) and IDE tooltips surface the same information.

📚 Documentation & Resources#

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

Made with ❤️ by the Biotuner development team

Indices and tables#

Contents