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

sequences (Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) – The to-be-concatenated objects.
name (Optional[str], 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.

Note

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

Parameters

sound_sequences (Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) – The to-be-concatenated objects.
name (Optional[str], 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.

Parameters

sound_stimuli (Union[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_interval_ratios_from_dyads(sequence)[source]#

Return sequential interval ratios, calculated as:

\(\textrm{ratio}_k = \frac{\textrm{IOI}_k}{\textrm{IOI}_k + \textrm{IOI}_{k+1}}\).

Note that for n IOIs this property returns n-1 ratios.

Parameters: sequence (Union[array, Sequence, list]) – The sequence from which to calculate the interval ratios. Can be a Sequence object, or a list or array of IOIs.

Notes

The used method is based on the methodology from Roeske et al. [RTPJ20].

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 (Union[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.

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.get_phase_differences(test_sequence, reference_sequence, circular_unit='degrees')[source]#

Get the phase differences for test_sequence compared to reference_sequence. If the second argument is a number, test_sequence will be compared with an isochronous sequence with a constant inter-onset interval (IOI) of that number and the same length as the test sequence.

Caution

The phase differences are calculated for each onset of test_sequence compared to the onset with the same index of reference_sequence. Missing values are discarded. In addition, if the first onset of the test sequence is at t = 0, that phase difference is also discarded.

Parameters

test_sequence (Sequence) – The sequence to be compared with the reference sequence. Can either be a single Sequence or a list or array of Sequences.
reference_sequence (Union[Sequence, float]) – The reference sequence. Can be a Sequence object, a list or array of Sequence objects, or a number. In the latter case, the reference sequence will be an isochronous sequence with a constant IOI of that number and the same length as sequence_1.
circular_unit (default: 'degrees') – The unit of the circular unit. Can be “degrees” or “radians”.

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