Visualization#

thebeat.visualization.phase_space_plot(sequence, style='seaborn-v0_8', linecolor='black', linewidth=0.5, title=None, x_axis_label='$\\\\mathregular{IOI_t}$', y_axis_label='$\\\\mathregular{IOI_{t+1}}$', figsize=None, suppress_display=False, dpi=100, ax=None)[source]#

Plot the phase space of a sequence. In such a plot we loop over each IOI, and plot a line between it on the x axis and the IOI that follows it on the y axis.

Parameters:

  • sequence (Sequence) – The sequence to plot.

  • style (str, default: 'seaborn-v0_8') – The matplotlib style to use. See matplotlib style reference.

  • linecolor (str, default: 'black') – The color of the lines.

  • linewidth (float, default: 0.5) – The width of the lines.

  • title (Optional[str], default: None) – A title for the plot.

  • x_axis_label (str, default: '$\\\\mathregular{IOI_t}$') – The label for the x axis.

  • y_axis_label (str, default: '$\\\\mathregular{IOI_{t+1}}$') – The label for the y axis.

  • figsize (Optional[tuple[int, int]], default: None) – The size of the figure to be created in inches, width x height, e.g. (4, 4).

  • suppress_display (bool, default: False) – If True, the figure will not be displayed.

  • dpi (int, default: 100) – The resolution of the figure in dots per inch.

  • ax (Optional[Axes], default: None) – An optional matplotlib Axes object to plot on. If not provided, a new Axes object will be created. If an Axes object is provided, this function returns the original Figure and Axes objects.

Return type:

tuple[Figure, Axes]

Example

../_images/phase_space_plot.png

Example of a phase space plot.#

Note

Code adapted from Ravignani and Norton [RN17].

Examples

>>> from thebeat import Sequence
>>> seq = Sequence.generate_random_normal(100,100,10)
>>> phase_space_plot(seq)
thebeat.visualization.plot_interval_ratios_density(sequence, resolution=0.01, style='seaborn-v0_8', title=None, x_axis_label='Interval ratios from dyads', y_axis_label='Probability density', figsize=None, suppress_display=False, dpi=100, ax=None)[source]#

Plot a density plot of the interval ratios from sequential dyads in a sequence. Input can either be a single sequence, or a list or array of sequences.

This function internally uses thebeat.utils.get_interval_ratios_from_dyads() to calculate the interval ratios.

Example

../_images/interval_ratios_density.png

Example interval ratios density plot.#

Parameters:

  • sequence (Sequence | list[Sequence] | ndarray[Sequence]) – The sequence or list or array of sequences to plot.

  • resolution (float, default: 0.01) – The resolution of the density plot. At each point, the probability density is calculated.

  • style (str, default: 'seaborn-v0_8') –

    The matplotlib style to use. See matplotlib style reference.

  • title (Optional[str], default: None) – A title for the plot.

  • x_axis_label (str, default: 'Interval ratios from dyads') – The label for the x axis.

  • y_axis_label (str, default: 'Probability density') – The label for the y axis.

  • figsize (Optional[tuple[int, int]], default: None) – The size of the figure to be created in inches, width x height, e.g. (4, 4).

  • suppress_display (bool, default: False) – If True, the figure will not be displayed.

  • dpi (int, default: 100) – The resolution of the figure in dots per inch.

  • ax (Optional[Axes], default: None) – An optional matplotlib Axes object to plot on. If not provided, a new Axes object will be created. If an Axes object is provided, this function returns the original Figure and Axes objects.

Return type:

tuple[Figure, Axes]

thebeat.visualization.plot_interval_ratios_histogram(sequence, bins=100, style='seaborn-v0_8', title=None, x_axis_label='Interval ratios from dyads', y_axis_label='Count', figsize=None, suppress_display=False, dpi=100, ax=None)[source]#

Plot a histogram of the interval ratios from sequential dyads in a sequence. Input can either be a single sequence, or a list or array of sequences.

This function internally uses thebeat.utils.get_interval_ratios_from_dyads() to calculate the interval ratios.

Example

../_images/interval_ratios_hist.png

Example interval ratios histogram.#

Parameters:

  • sequence (Sequence | list[Sequence] | ndarray[Sequence]) – The sequence or list or array of sequences to plot.

  • bins (int, default: 100) – The number of bins to use in the histogram.

  • style (str, default: 'seaborn-v0_8') –

    The matplotlib style to use. See matplotlib style reference.

  • title (Optional[str], default: None) – A title for the plot.

  • x_axis_label (str, default: 'Interval ratios from dyads') – The label for the x axis.

  • y_axis_label (str, default: 'Count') – The label for the y axis.

  • figsize (Optional[tuple[int, int]], default: None) – The size of the figure to be created in inches, width x height, e.g. (4, 4).

  • suppress_display (bool, default: False) – If True, the figure will not be displayed.

  • dpi (int, default: 100) – The resolution of the figure in dots per inch.

  • ax (Optional[Axes], default: None) – An optional matplotlib Axes object to plot on. If not provided, a new Axes object will be created. If an Axes object is provided, this function returns the original Figure and Axes objects.

Return type:

tuple[Figure, Axes]

thebeat.visualization.plot_multiple_sequences(sequences, style='seaborn-v0_8', title=None, x_axis_label='Time', y_axis_labels=None, linewidths=None, figsize=None, suppress_display=False, dpi=100, colors=None, ax=None)[source]#

Plot multiple sequences in one plot. Either pass it a list or array of Sequence objects, SoundSequence objects, or list or array of event onsets (so e.g. list of lists).

Parameters:

  • sequences (list | ndarray) – A list or array of Sequence or SoundSequence objects. Alternatively, one can provide e.g. a list of lists containing event onsets, for instance: [[0, 500, 1000], [0, 600, 800], [0, 400, 550]].

  • style (str, default: 'seaborn-v0_8') – Matplotlib style to use for the plot. See matplotlib style sheets reference.

  • x_axis_label (str, default: 'Time') – A label for the x axis.

  • y_axis_labels (UnionType[list[str], ndarray[str], None], default: None) – A list or array containing names for the sequences as strings. For instance ['Sequence 1', 'Sequence 2'] etc. Must be of the same length as the number of sequences passed. If no names are provided, defaults to numbering the sequences. This is because matplotlib needs a label there.

  • title (Optional[str], default: None) – If desired, one can provide a title for the plot. This takes precedence over using the Sequence or SoundSequence name as the title of the plot (if passed and the object has one).

  • linewidths (UnionType[list[float], ndarray[Any, dtype[float]], float, None], default: None) – An array or list of ints (e.g. [50, 50, 50] ) or nested array or list containing the desired widths of the bars (event durations), for instance: [[50, 30, 60], [20, 40, 10], [60, 30, 10]]. By default, if SoundSequence objects are passed, the event durations are used. In other cases, a default of 1/10th of the smallest IOI is used.

  • figsize (Optional[tuple], default: None) – A tuple containing the desired output size of the plot in inches, e.g. (4, 1). This refers to the figsize parameter in matplotlib.pyplot.figure().

  • suppress_display (bool, default: False) – If True, the plot is only returned, and not displayed via matplotlib.pyplot.show().

  • dpi (int, default: 100) – The resolution of the plot in dots per inch. This refers to the dpi parameter in matplotlib.pyplot.figure().

  • colors (list | ndarray, default: None) – A list or array of colors to use for the plot. If not provided, the default matplotlib colors are used. Colors may be provided as strings (e.g. 'red') or as RGB tuples (e.g. (1, 0, 0)).

  • ax (Optional[Axes], default: None) – If desired, you can provide an existing matplotlib.axes.Axes object onto which to plot. See the Examples of the different plotting functions to see how to do this (e.g. plot_sequence() ). If an existing matplotlib.axes.Axes object is supplied, this function returns the original matplotlib.figure.Figure and matplotlib.axes.Axes objects.

Return type:

tuple[Figure, Axes]

Examples

>>> from thebeat.core import Sequence
>>> generator = np.random.default_rng(seed=123)
>>> seqs = [Sequence.generate_random_normal(n_events=5,mu=5000,sigma=50,rng=generator) for _ in range(10)]
>>> plot_multiple_sequences(seqs,linewidths=50)  

>>> seq1 = Sequence([500, 100, 200])
>>> seq2 = Sequence([100, 200, 500])
>>> fig, ax = plot_multiple_sequences([seq1, seq2],colors=['red', 'blue'])  
>>> fig.savefig('test.png')
thebeat.visualization.plot_phase_differences(test_sequence, reference_sequence, reference_ioi='preceding', window_size=None, modulo=True, circular_unit='degrees', binwidth=10, zero_direction='E', color=None, style='seaborn-v0_8', title=None, figsize=None, suppress_display=False, dpi=100, ax=None)[source]#

Plot the phase differences for test_sequence compared to reference_sequence.

The reference sequence can either be a single sequence in which case a comparison will be made between each test sequence and the reference sequence, or a float in which case a comparison will be made between each test sequence and an isochronous sequence with the provided IOI, or it can be an array or list of sequences, in which case a comparison is made between each test and reference sequence element-wise.

Example

../_images/phase_differences_plot.png

Example phase differences plot.#

Parameters:

  • test_sequence (Sequence) – The sequence or sequences to be compared to reference_sequence. Can be a single thebeat.core.Sequence object, or a list or array of thebeat.core.Sequence objects.

  • reference_sequence (Sequence) – The reference sequence or sequences to be compared to test_sequence. Can be a single thebeat.core.Sequence object, or a list or array of thebeat.core.Sequence objects. If both the test_sequence and reference sequences are lists or arrays, they must be of the same length.

  • circular_unit (str, default: 'degrees') – The unit of the circular data. Can be ‘degrees’ or ‘radians’.

  • binwidth (int, default: 10) – The width of the bins used to calculate the histogram bars.

  • zero_direction (str, default: 'E') – The direction of the zero angle. Can be ‘N’, ‘E’, ‘S’, or ‘W’.

  • color (str, default: None) – The color of the bars. Can be a single color or a list of colors, one for each bar. See matplotlib.axes.Axes.bar() for more information.

  • style (str, default: 'seaborn-v0_8') –

    The matplotlib style to use. See matplotlib style reference.

  • title (Optional[str], default: None) – A title for the plot.

  • figsize (Optional[tuple[int, int]], default: None) – The size of the figure to be created in inches.

  • suppress_display (bool, default: False) – If True, the figure will not be displayed.

  • dpi (int, default: 100) – The resolution of the figure in dots per inch.

  • ax (Optional[Axes], default: None) – An optional matplotlib.axes.Axes object to plot on. If not provided, a new Axes object will be created. If an matplotlib.axes.Axes object is provided, the function returns the original matplotlib.figure.Figure and matplotlib.axes.Axes objects.

Return type:

tuple[Figure, Axes]

thebeat.visualization.recurrence_plot(sequence, threshold=None, colorbar=False, colorbar_label='Distance', cmap=None, style='seaborn-v0_8', title=None, x_axis_label='$\\\\mathregular{N_i}$', y_axis_label='$\\\\mathregular{N_i}$', figsize=(5, 4), suppress_display=False, dpi=100, ax=None)[source]#

Plot a recurrence plot of a sequence. A recurrence plot is a plot with the IOI numbers (i.e. their indices) on the x and y axis, and the distance between the IOIs on the color scale. For each combination of two IOIs, the distance between these IOIs is calculated as their absolute difference (which may for instance be in seconds or milliseconds, depending on your input during construction of the Sequence object).

If you provide a threshold, the plot will be binary, where color indicates anything below the threshold, and where white indicates anything above the threshold.

Example

../_images/recurrence_plot.png

Example recurrence plot with colorbar=True.#

Parameters:

  • sequence (Sequence) – A Sequence object.

  • threshold (Optional[float], default: None) – The threshold to use for the recurrence plot. If a threshold is given, the plot is binary, with color (e.g. black) representing the inter-onset intervals that are below the threshold. If no threshold is given, the plot is colored according to the distance between the inter-onset intervals.

  • colorbar (bool, default: False) – If True, a colorbar is added to the plot. Note that no colorbar is plotted when an existing Axes object is provided.

  • colorbar_label (Optional[str], default: 'Distance') – A label for the colorbar.

  • cmap (Optional[str], default: None) – The colormap to use for the plot. See matplotlib colormaps reference for the different options. For binary plots, the default is 'Greys', for colored plots, the default is 'viridis'.

  • style (str, default: 'seaborn-v0_8') –

    Matplotlib style to use for the plot. See matplotlib style sheets reference.

  • title (Optional[str], default: None) – If desired, one can provide a title for the plot.

  • x_axis_label (str, default: '$\\\\mathregular{N_i}$') – A label for the x axis.

  • y_axis_label (str, default: '$\\\\mathregular{N_i}$') – A label for the y axis.

  • figsize (tuple, default: (5, 4)) – A tuple containing the desired output size of the plot in inches, e.g. (4, 1).

  • suppress_display (bool, default: False) – If True, the plot is only returned, and not displayed via matplotlib.pyplot.show().

  • dpi (int, default: 100) – The resolution of the plot in dots per inch.

  • ax (Optional[Axes], default: None) – If desired, you can provide an existing matplotlib.axes.Axes object onto which to plot. See the Examples of the different plotting functions to see how to do this (e.g. plot_sequence() ). If an existing matplotlib.axes.Axes object is supplied, this function returns the original matplotlib.figure.Figure and matplotlib.axes.Axes objects.

Return type:

tuple[Figure, Axes]

Examples

>>> from thebeat.core import Sequence
>>> from thebeat.visualization import recurrence_plot
>>> seq = Sequence.generate_random_normal(n_events=3,mu=5000,sigma=50,end_with_interval=True) * 10
>>> recurrence_plot(seq)  

>>> fig, ax = recurrence_plot(seq, dpi=300, colorbar=True)
>>> fig.savefig('recurrence_plot.png', bbox_inches='tight')  

>>> seq = Sequence.generate_random_normal(n_events=3,mu=5000,sigma=50,end_with_interval=True) * 10
>>> fig, ax = recurrence_plot(seq, threshold=5, dpi=300, suppress_display=True)
>>> fig.savefig('recurrence_plot.png')

Notes

The binary recurrence plot is based on Ravignani and Norton [RN17]. The coloured recurrence plot is based on Burchardt et al. [BBKnornschild21].