Utilities#

These are helper functions that are used throughout the package.

thebeat.utils.concatenate_sequences(sequences, name=None)[source]#

Concatenate an array or list of Sequence objects.

Note

Only works for Sequence objects where all but the last provided object has an end_with_interval=True flag.

Parameters:
Returns:

The concatenated Sequence

Return type:

object

thebeat.utils.concatenate_soundsequences(sound_sequences, name=None)[source]#

Concatenate an array or list of SoundSequence objects.

Note

Only works for SoundSequence objects where all but the last provided object has an end_with_interval=True flag.

Parameters:
Returns:

The concatenated SoundSequence

Return type:

object

thebeat.utils.concatenate_soundstimuli(sound_stimuli, name=None)[source]#

Concatenate an array or list of SoundStimulus objects.

Parameters:

  • sound_stimuli (ndarray | list) – The to-be-concatenated objects.

  • name (Optional[str], default: None) – Optionally, you can give the returned SoundStimulus object a name.

Returns:

The concatenated SoundStimulus

Return type:

object

thebeat.utils.get_ioi_df(sequences, additional_functions=None)[source]#

This function exports a Pandas pandas.DataFrame with information about the provided thebeat.core.Sequence objects in tidy data format. The DataFrame always has the columns:

  • Sequence_index: The index of the Sequence object in the list of Sequences.

  • IOI_i: The index of the IOI in the Sequence.

  • IOI: The IOI.

Additionally it has a column Sequence_name if at least one of the provided Sequence objects has a name.

Moreover, one can provide a list of functions that will be applied to each sequence’s IOIs. The results will be added as additional columns in the output DataFrame. See under ‘Examples’ for an illustration.

Parameters:

  • sequences (Sequence | list[Sequence] | ndarray[Sequence]) – The Sequence object(s) to be exported.

  • additional_functions (Optional[list[callable]], default: None) – A list of functions that will be applied to the IOIs for each individual sequence, and the results of which will be added as additional columns.

Returns:

A Pandas DataFrame with information about the provided Sequence objects in tidy data format.

Return type:

pd.DataFrame

Examples

>>> rng = np.random.default_rng(123)
>>> seqs = [thebeat.core.Sequence.generate_random_normal(n_events=10, mu=500, sigma=25, rng=rng) for _ in range(10)]
>>> df = get_ioi_df(seqs)
>>> print(df.head())
   sequence_i  ioi_i         ioi
0           0      0  475.271966
1           0      1  490.805334
2           0      2  532.198132
3           0      3  504.849360
4           0      4  523.005772

>>> import numpy as np
>>> df = get_ioi_df(seqs, additional_functions=[np.mean, np.std])
>>> print(df.head())
   sequence_i        mean        std  ioi_i         ioi
0           0  503.364499  17.923263      0  475.271966
1           0  503.364499  17.923263      1  490.805334
2           0  503.364499  17.923263      2  532.198132
3           0  503.364499  17.923263      3  504.849360
4           0  503.364499  17.923263      4  523.005772
thebeat.utils.get_major_scale(tonic, octave)[source]#

Get the major scale for a given tonic and octave. Returns a list of abjad.pitch.NamedPitch objects.

Note

This function requires abjad to be installed. It can be installed with pip install abjad or pip install thebeat[music_notation]. For more details, see https://thebeat.readthedocs.io/en/latest/installation.html.

Parameters:

  • tonic (str) – The tonic of the scale, e.g. ‘G’.

  • octave (int) – The octave of the scale, e.g. 4.

Returns:

A list of abjad.pitch.NamedPitch objects.

Return type:

pitches

thebeat.utils.merge_sequences(sequences, name=None)[source]#

Merge an array or list of Sequence objects. The the event onsets in each of the objects will be overlaid on top of each other.

Parameters:

  • sequences – The to-be-merged objects.

  • name (default: None) – Optionally, you can give the returned Sequence object a name.

Returns:

The merged Sequence

Return type:

object

thebeat.utils.merge_soundsequences(sound_sequences, name=None)[source]#

Merge a list or array of SoundSequence objects. The event onsets in each of the objects will be overlaid on top of each other, after which the sounds

Parameters:

  • sound_sequences (list[SoundSequence]) – The to-be-merged objects.

  • name (Optional[str], default: None) – Optionally, you can give the returned SoundSequence object a name.

Returns:

The merged SoundSequence

Return type:

object

thebeat.utils.merge_soundstimuli(sound_stimuli, name=None)[source]#

Merge an array or list of SoundStimulus objects. The sound samples for each of the objects will be overlaid on top of each other.

Parameters:

  • sound_stimuli – The to-be-merged objects.

  • name (default: None) – Optionally, you can give the returned SoundStimulus object a name.

Returns:

The merged SoundStimulus

Return type:

object