Utilities

Utilities#

These are helper functions that are used throughout the package.

thebeat.utils.concatenate_rhythms(rhythms, name=None)[source]#

Concatenate an array or list of Rhythm objects.

The resulting Rhythm object contains the rhythms in order.

Parameters:
Returns:

The concatenated Rhythm

Return type:

object

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

Concatenate an array or list of Sequence objects.

The resulting Sequence object contains the sequences in order.

Note

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

Parameters:

  • sequences (Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], complex, bytes, str, _NestedSequence[complex | bytes | str]]) – The to-be-concatenated objects.

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

Returns:

The concatenated Sequence

Return type:

object

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

Concatenate an array or list of SoundSequence objects.

The resulting SoundSequence object contains the sound sequences in order.

Note

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

Parameters:

  • sound_sequences (Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], complex, bytes, str, _NestedSequence[complex | bytes | str]]) – The to-be-concatenated objects.

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

Returns:

The concatenated SoundSequence

Return type:

object

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

Concatenate an array or list of SoundStimulus objects.

The resulting SoundStimulus object contains the sound stimuli in order.

Parameters:

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

  • name (str | None, 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 (list[callable] | None, 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.

Parameters:

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

  • name (str | None, 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

thebeat.utils.rhythm_to_binary(rhythm, smallest_note_value=Fraction(1, 16))[source]#

Convert a rhythm to a binary representation, consisting of zeros and ones.

The time range of Rhythm will be discretized based on the provided smallest note value. For example, for a smallest_note_value of 1/6, each 4/4 bar will result in a list of 16 ones and zeros. Each event (or note) within the Rhythm object will be respresented as a 1, and all other entries will be 0, resulting in a binary representation of the rhythm.

Examples

>>> rhythm = thebeat.music.Rhythm.from_note_values([1/4, 1/2, 1/8, 1/8])
>>> rhythm_to_binary(rhythm, smallest_note_value=Fraction(1, 16))
array([1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0], dtype=uint8)
>>> rhythm_to_binary(rhythm, smallest_note_value=1/8)
array([1, 0, 1, 0, 0, 0, 1, 1], dtype=uint8)
Parameters:

  • rhythm (Rhythm) – The object to be converted to a binary representation.

  • smallest_note_value (float | Fraction, default: Fraction(1, 16)) – The note value to be used as grid size for the discretization. Default value: Fraction(1, 16).

Returns:

The binary representation of the rhythm.

Return type:

np.ndarray[np.uint8]

thebeat.utils.sequence_to_binary(sequence, resolution)[source]#

Convert a sequence to a binary representation, consisting of ones and zeros.

The time range of The full duration is split up into parts, each part corresponding to the provided ``resolution`. Each event of the Sequence object will be respresented as a 1, and all others element 0, in the resulting binary representation of the sequence.

Examples

>>> seq = thebeat.Sequence([110, 185, 90])
>>> sequence_to_binary(seq, resolution=100)
array([1, 1, 0, 1, 1], dtype=uint8)
>>> sequence_to_binary(seq, resolution=50)
array([1, 0, 1, 0, 0, 0, 1, 0, 1], dtype=uint8)
Parameters:

  • rhythm – The object to be converted to a binary representation.

  • resolution (int | float) – The resolution of the temporal discretization.

Returns:

The binary representation of the sequence.

Return type:

np.ndarray[np.uint8]

Contents