thebeat: Rhythms in Python for Science

thebeat is a Python package for working with temporal sequences and rhythms in the behavioural and cognitive sciences. It provides functionality for creating stimuli, and for visualizing and analyzing temporal data.

As a collection of accepted methods for use in music and timing research, thebeat will save you time when creating experiments or analyzing data.

thebeat is an open-source, on-going, and collaborative project, integrating easily with the existing Python ecosystem, and with your own scripts. The package was specifically designed to be useful for both skilled and novice programmers.

Documentation

The package documentation is available from https://thebeat.readthedocs.io. The documentation contains detailed descriptions of all package functionality, as well as a large number of (copyable) examples.

Installation

thebeat is available through PyPI, and can be installed using:

pip install thebeat

Note that if you want to use thebeat's functionality for plotting musical notation, you have to install it using:

pip install 'thebeat[music-notation]'

This will install thebeat with the optional dependencies abjad and Lilypond.

thebeat is actively tested on Linux, macOS, and Windows. We aim to provide support for all supported versions of Python (3.10 and higher).

Try directly via Binder

If you first would like to try thebeat, or of you wish to use it in, for instance, an educational setting, you can use this link to try thebeat in a Binder environment.

Getting started

The code below illustrates how we might create a simple trial for use in an experiment:

from thebeat import Sequence, SoundStimulus, SoundSequence

seq = Sequence.generate_isochronous(n_events=10, ioi=500)
sound = SoundStimulus.generate(freq=440, duration_ms=50, onramp_ms=10, offramp_ms=10)
trial = SoundSequence(sound, seq)

trial.play()  # play sound over loudspeakers
trial.plot_waveform()  # plot as sound waveform
trial.plot_sequence()  # plot as an event plot
trial.write_wav('example_trial.wav')  # save file to disk

Open discussion

One of the reasons for creating thebeat was the lack of a collection of standardized/accepted methods for use in rhythm and timing research. Therefore, an important part of thebeat's merit lies in opening discussions about the methods that are included. As an example, there are different ways of calculating phase differences and integer ratios, and we imagine people to have different opinions about which method to use. Where possible, we have included references to the literature in the package documentation. But, we encourage anyone with an opinion to openly question the methods that thebeat provides.

There are two places where you can go with comments and/or questions:

• You can click the 'Issues' tab at the top of this GitHub page, and start a thread. Note that this place is mostly for questioning methods, or for reporting bugs.
• You can drop by in our Gitter chatroom. This is likely the best place to go to with questions about how thebeat works.

License

thebeat is distributed under the GNU General Public License, version 3 or later. You are free to distribute or modify the code, both for non-commercial and commercial use. See here for more info.

Acknowledgements

The package was initially developed by the Comparative Bioacoustics Group at the Max Planck Institute for Psycholinguistics, in Nijmegen, the Netherlands. It is currently maintained by the same group at Sapienza University of Rome, Italy.

The collaborators are Jelle van der Werff, Andrea Ravignani, and Yannick Jadoul.

thebeat was described in an article in Behavior Research Methods:

van der Werff, J., Ravignani, A., & Jadoul, Y. (2024). thebeat: A python package for working with rhythms and other temporal sequences. Behavior Research Methods, 56(4), 3725–3736. https://doi.org/10.3758/s13428-023-02334-8

Check out the documentation for more details on citing thebeat.