bycycle.plts.plot_burst_detect_summary

bycycle.plts.plot_burst_detect_summary(df_features, sig, fs, threshold_kwargs, xlim=None, figsize=(15, 3), plot_only_result=False, interp=True)[source]

Plot the cycle-by-cycle burst detection parameters and burst detection summary.

Parameters:
df_featurespandas.DataFrame

Dataframe output of compute_features(). The df must contain sample indices (i.e. when return_samples = True).

sig1d array

Time series to plot.

fsfloat

Sampling rate, in Hz.

threshold_kwargsdict

Burst parameter keys and threshold value pairs, as defined in the ‘threshold_kwargs’ argument of compute_features().

xlimtuple of (float, float), optional, default: None

Start and stop times for plot.

figsizetuple of (float, float), optional, default: (15, 3)

Size of each plot.

plot_only_resultbool, optional, default: False

Plot only the signal and bursts, excluding burst parameter plots.

interpbool, optional, default: True

If True, interpolates between given values. Otherwise, plots in a step-wise fashion.

Notes

  • If plot_only_result = True: return a plot of the burst detection in which periods with bursts are denoted in red.

  • If plot_only_result = False: return a list of the fig handle followed by the 5 axes.

  • In the top plot, the raw signal is plotted in black, and the red line indicates periods defined as oscillatory bursts. The highlighted regions indicate when each burst requirement was violated, color-coded consistently with the plots below.

    • blue: amp_fraction_threshold

    • red: amp_consistency_threshold

    • yellow: period_consistency_threshold

    • green: monotonicity_threshold

Examples

Plot the burst detection summary of a bursting signal:

>>> from bycycle.features import compute_features
>>> from neurodsp.sim import sim_bursty_oscillation
>>> fs = 500
>>> sig = sim_bursty_oscillation(10, fs, freq=10)
>>> threshold_kwargs = {'amp_fraction_threshold': 0., 'amp_consistency_threshold': .5,
...                     'period_consistency_threshold': .5, 'monotonicity_threshold': .8}
>>> df_features = compute_features(sig, fs, f_range=(8, 12), threshold_kwargs=threshold_kwargs)
>>> plot_burst_detect_summary(df_features, sig, fs, threshold_kwargs)