Getting started¶
This document is intended to get you started as quickly as possible. We discuss two important underlying concepts, the package's core classes and how to combine them, and we end with a simple example in which we create a trial as might be used in an auditory perception experiment.
# We suppress warnings, but let's hide that to avoid confusion
import warnings
warnings.filterwarnings('ignore')
%matplotlib inline
Step 1: Concepts¶
Consider the example sequence given below:
Inter-onset intervals (IOIs) and onsets¶
For timing sequences and events, throughout this package we make the most use of inter-onset intervals (IOIs). IOIs represent the interval between the onset of one event, and the onset of the next event. Because IOIs are onset-to-onset, which is different from inter-stimulus intervals (which are offset-to-onset), we can think about these sequences in terms of rhythms. This because often the duration of the event is irrelevant to the type of beat that is induced in the listener.
End sequence with event or interval¶
An important concept to mention here is that sequences can end with an event, or end with an interval. In effect, this means that sequences that end with an event have n events, but n-1 IOIs. Sequences that end with an interval have n events and n IOIs. The default is for sequences to end with an event, but for rhythms or for combining sequences we need sequences that end with an interval. Otherwise, we would not know what interval to place between the offset of the final event in a sequence and the onset of the first event in the next sequence.
Step 2: Combining and converting between classes¶
At this point the most important thing to remember is that the Sequence class is the one you will be using most.
Step 3: Your first trial¶
Here we will create a simple isochronous (i.e. regular) trial of 10 events at a tempo of 500 ms (i.e. each IOI is 500 ms, corresponding to 120 bpm or 2 hertz). It contains the same pure tone sound stimulus of 50 ms at a pitch of 440Hz with a linear on- and offramp (attack/decay) of each 10 ms.
from thebeat import Sequence, SoundStimulus, SoundSequence
seq = Sequence.generate_isochronous(n_events=10, ioi=500)
stim = SoundStimulus.generate(freq=440, duration_ms=50, onramp_ms=10, offramp_ms=10)
trial = SoundSequence(stim, 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
