SoundSequence class

The SoundSequence class is a combination of the sound of a SoundStimulus (or stimuli) and the timing information from a Sequence.

class thebeat.core.SoundSequence(sound, sequence, sequence_time_unit='ms', name=None)

The SoundSequence class can be thought of as a combination of the SoundStimulus class and the Sequence class; hence SoundSequence. It combines the timing information of a Sequence object with the auditory information (sound) of a SoundStimulus object. In most research one would refer to a SoundSequence as a trial (which is also the variable name used in some of the examples here). Remember that a Sequence object is agnostic about the used time unit, so when constructing a SoundSequence object, you can specify the time unit of the Sequence object using the sequence_time_unit parameter (see under Sequence.__init__().

One can construct a SoundSequence object either by passing it a single SoundStimulus object (and a Sequence object), or by passing it an array or list of SoundStimulus objects (and a Sequence object).

If a single SoundStimulus object is passed, this SoundStimulus sound is used for each event onset. Otherwise, each SoundStimulus sound is used for its respective event onsets. Of course, then the number of SoundStimulus objects in the iterable must be the same as the number of event onsets.

SoundSequence objects can be plotted, played, written to disk, statistically analyzed, and more… During construction, checks are done to ensure you dit not accidentally use sounds that are longer than the IOIs (impossible), that the sampling frequencies of all the SoundStimulus objects are the same (undesirable), and that the SoundStimulus objects’ number of channels are the same (probable).

__init__(sound, sequence, sequence_time_unit='ms', name=None)

Initialize a SoundSequence object using a SoundStimulus object, or list or array of SoundStimulus objects, and a Sequence object.

During the construction of a SoundSequence object, sound is generated on the basis of the passed SoundStimulus objects and the passed Sequence object. A warning is issued if the frame number, where one of the sounds would be placed, had to be rounded off. To get rid of this warning, you can use the Sequence.round_onsets() method before passing it to the :py:class`SoundSequence` constructor, or try a different sampling frequency for the :py:class`SoundStimulus` sound.

Parameters:

• sound (SoundStimulus | list[SoundStimulus] | ndarray[Any, dtype[SoundStimulus]]) – Either a single SoundStimulus object (in which case the same sound is used for each event onset), or a list or array of SoundStimulus objects (in which case different sounds are used for each event onset).

• sequence (Sequence) – A Sequence object. This contains the timing information for the played events.

• sequence_time_unit (str, default: 'ms') – If the Sequence object was created using seconds, use “s”. The default is milliseconds (“ms”).

• name (Optional[str], default: None) – You can provide a name for the SoundSequence which is sometimes used (e.g. when printing the object, or when plotting one). You can always retrieve this attribute from SoundSequence.name.

Examples

>>> sound = SoundStimulus.generate(freq=440)
>>> seq = Sequence.generate_isochronous(n_events=5, ioi=500)
>>> trial = SoundSequence(sound, seq)

>>> from random import randint
>>> sounds = [SoundStimulus.generate(freq=randint(100, 1000)) for x in range(5)]
>>> seq = Sequence.generate_isochronous(n_events=5, ioi=500)
>>> trial = SoundSequence(sounds, seq)

copy(deep=True)

Returns a copy of itself. See copy.copy() for more information.

Parameters:

deep (bool, default: True) – If True, a deep copy is returned. If False, a shallow copy is returned.

property duration: float64

Property that returns the summed total of the inter-onset intervals.

property iois: ndarray

property mean_ioi: float64

The average inter-onset interval (IOI).

merge(other)

Merge this SoundSequence object with one or multiple other SoundSequence objects.

Returns a new SoundSequence object.

Parameters:

other (SoundSequence | list[SoundSequence]) – A SoundSequence object, or a list of SoundSequence objects.

Returns:

A SoundSequence object.

Return type:

object

property onsets: ndarray

Returns the event onsets (t values) on the basis of the sequence objects’ inter-onset intervals (IOIs).

play(loop=False, metronome=False, metronome_amplitude=1.0)

This method uses the sounddevice.play() to play the object’s audio.

Parameters:

• loop (bool, default: False) – If True, the SoundSequence will continue playing until the SoundSequence.stop() method is called.

• metronome (bool, default: False) – If True, a metronome sound is added for playback.

• metronome_amplitude (float, default: 1.0) – If desired, when playing the object with a metronome sound you can adjust the metronome amplitude. A value between 0 and 1 means a less loud metronome, a value larger than 1 means a louder metronome sound.

Examples

>>> sound = SoundStimulus.generate(offramp_ms=10)
>>> seq = Sequence.generate_random_normal(n_events=10, mu=500, sigma=50)
>>> seq.round_onsets()
>>> soundseq = SoundSequence(sound, seq)
>>> soundseq.play(metronome=True)  

plot_sequence(linewidth=None, **kwargs)

Plot the SoundSequence object as an event plot on the basis of the event onsets and their durations. See thebeat.visualization.plot_single_sequence().

Parameters:

• linewidth (UnionType[float, list[float], ndarray[Any, dtype[float]], None], default: None) – The desired width of the bars (events). Defaults to the event durations. Can be a single value that will be used for each onset, or a list or array of values (i.e with a value for each respective onsets).

• **kwargs – Additional parameters (e.g. ‘title’, ‘dpi’ etc.) are passed to thebeat._helpers.plot_single_sequence().

Examples

>>> sound = SoundStimulus.generate()
>>> seq = Sequence.generate_isochronous(n_events=5,ioi=500)
>>> trial = SoundSequence(sound, seq)
>>> trial.plot_sequence()  

plot_waveform(**kwargs)

Plot the SoundSequence object as a waveform.

Parameters:

**kwargs – Additional parameters (e.g. ‘title’, ‘dpi’ are passed to thebeat.helpers.plot_waveform()).

Examples

>>> sound = SoundStimulus.generate()
>>> seq = Sequence.generate_isochronous(n_events=10,ioi=500)
>>> trial = SoundSequence(sound, seq)
>>> trial.plot_waveform()  

stop()

Stop playing the SoundSequence sound. Calls sounddevice.stop().

Return type:

None

Examples

>>> import time  
>>> sound = SoundStimulus.generate()  
>>> seq = Sequence([500, 300, 800])  
>>> soundseq = SoundSequence(sound, seq)  
>>> soundseq.play()  
>>> time.sleep(secs=1)  
>>> soundseq.stop()  

static write_multichannel_wav(soundsequences, filepath, dtype=<class 'numpy.int16'>)

This is a static method that is used to write multiple SoundSequence objects to a single multichannel .wav file. This can e.g. be useful when creating stimuli that have a synchronization stimulus on one of the other (e.g. third) channels. This may be useful e.g. for EEG experiments.

Parameters:

soundsequences (list[SoundSequence]) – A list of SoundSequence objects.

Examples

>>> sound = SoundStimulus.generate()
>>> seq1 = Sequence.generate_random_normal(n_events=5, mu=500, sigma=50)
>>> seq1.round_onsets()
>>> seq2 = Sequence.generate_isochronous(n_events=5, ioi=500)
>>> trial1 = SoundSequence(sound, seq1)
>>> trial2 = SoundSequence(sound, seq2)
>>> SoundSequence.write_multichannel_wav([trial1, trial2], 'my_soundseqs.wav')  

write_wav(filepath, dtype=<class 'numpy.int16'>, metronome=False, metronome_ioi=None, metronome_amplitude=None)

Parameters:

• filepath (str | PathLike) – The output destination for the .wav file. Either pass e.g. a Path object, or a pass a string. Of course be aware of OS-specific filepath conventions.

• dtype (str | dtype, default: <class 'numpy.int16'>) – The data type of the samples. Defaults to np.int16, meaning that the samples are saved as 16-bit integers.

• metronome (bool, default: False) – If True, a metronome sound is added for playback.

• metronome_ioi (Optional[float], default: None) – If desired, when playing the StimSequence with a metronome sound you can adjust the metronome inter-onset interval (IOI). Defaults to the mean IOI of the sequence.

• metronome_amplitude (Optional[float], default: None) – If desired, when playing the StimSequence with a metronome sound you can adjust the metronome amplitude. A value between 0 and 1 means a less loud metronme, a value larger than 1 means a louder metronome sound.

Examples

>>> sound = SoundStimulus.generate()
>>> seq = Sequence.generate_isochronous(n_events=5,ioi=500)
>>> soundseq = SoundSequence(sound, seq)
>>> soundseq.write_wav('my_soundseq.wav')