Surrogates

Surrogates#

Surrogate signal generation and comparison for BiotunerGroup analysis.

Module type: Functions

Surrogates are signal controls that preserve specific statistical properties (spectrum, amplitude distribution) while destroying others (phase relationships, nonlinear structure). Comparing real vs. surrogate BiotunerGroup metrics lets you assess whether observed harmonicity is above chance.

Typical usage#

>>> from biotuner.biotuner_group import BiotunerGroup
>>> from biotuner.surrogates import surrogate_group, plot_surrogate_distributions
>>>
>>> bt = BiotunerGroup(data, sf=1000)
>>> bt.compute_peaks(peaks_function='EMD').compute_metrics()
>>>
>>> surr = surrogate_group(bt, surr_type='AAFT')
>>> surr_pink = surrogate_group(bt, surr_type='pink')
>>>
>>> plot_surrogate_distributions(bt, {'AAFT': surr, 'pink': surr_pink}, metric='harmsim')
generate_surrogate(data: ndarray, surr_type: str = 'pink', low_cut: float = 0.5, high_cut: float = 150.0, sf: int = 1000, TFT_freq: int = 5) → ndarray[source]#

Generate a surrogate signal from a 1D time series.

Parameters:

  • data (ndarray, shape (n_samples,)) – Original 1D signal.

  • surr_type (str, default=’pink’) – Surrogate type:

    • 'AAFT' – Amplitude-Adjusted Fourier Transform surrogate. Preserves amplitude distribution and power spectrum.

    • 'TFT' – Truncated Fourier Transform surrogate. Preserves low-frequency structure below TFT_freq Hz.

    • 'phase' – Phase-scrambled surrogate. Preserves power spectrum, destroys phase relationships.

    • 'shuffle' – Randomly shuffled samples. Destroys all temporal structure.

    • 'white' – White noise (flat spectrum, β=0).

    • 'pink' – Pink noise (1/f spectrum, β=1).

    • 'brown' – Brown noise (1/f² spectrum, β=2).

    • 'blue' – Blue noise (f spectrum, β=−1).

  • low_cut (float, default=0.5) – High-pass cutoff frequency (Hz). Applied after generation for all types except TFT.

  • high_cut (float, default=150.0) – Low-pass cutoff frequency (Hz).

  • sf (int, default=1000) – Sampling frequency (Hz).

  • TFT_freq (int, default=5) – Corner frequency for TFT surrogates.

Returns:

surrogate (ndarray, shape (n_samples,)) – Surrogate signal matching the length of data.

generate_surrogate_data(data: ndarray, surr_type: str = 'pink', low_cut: float = 0.5, high_cut: float = 150.0, sf: int = 1000, **kwargs) → ndarray[source]#

Generate surrogate signals for a 2D or 3D array of time series.

Parameters:

  • data (ndarray, shape (n, n_samples) or (n, m, n_samples)) – Original signals. Each 1D slice is treated independently.

  • surr_type (str, default=’pink’) – Surrogate type. See generate_surrogate().

  • low_cut, high_cut (float) – Bandpass filter cutoffs (Hz).

  • sf (int, default=1000) – Sampling frequency (Hz).

  • **kwargs – Extra keyword arguments forwarded to generate_surrogate() (e.g. TFT_freq).

Returns:

surrogate_data (ndarray) – Same shape as data.

surrogate_group(bt_group, surr_type: str = 'AAFT', low_cut: float = 0.5, high_cut: float = 150.0, recompute: bool = True, n_jobs: int = 1, **peaks_kwargs)[source]#

Create a surrogate BiotunerGroup.

Generates surrogate signals for every time series in bt_group, then mirrors the same analysis pipeline (peaks, metrics, dissonance curve, …) that was already run on the original group.

Parameters:

  • bt_group (BiotunerGroup) – Reference group. Shape and sampling frequency are preserved.

  • surr_type (str, default=’AAFT’) – Surrogate type. See generate_surrogate().

  • low_cut, high_cut (float) – Bandpass filter cutoffs (Hz) applied during surrogate generation.

  • recompute (bool, default=True) – If True, automatically re-run the same analysis steps that were already computed on bt_group (peaks, metrics, diss_curve, HE).

  • n_jobs (int, default=1) – Parallel jobs forwarded to the BiotunerGroup pipeline.

  • **peaks_kwargs – Extra keyword arguments forwarded to compute_peaks() (e.g. min_freq=1, max_freq=60).

Returns:

surr_group (BiotunerGroup) – New BiotunerGroup backed by surrogate data, with the same pipeline state as bt_group (if recompute is True).

Examples

>>> surr = surrogate_group(bt, surr_type='AAFT', min_freq=1, max_freq=60)
>>> comparison = plot_surrogate_distributions(bt, {'AAFT': surr}, metric='harmsim')
plot_surrogate_distributions(real_group, surrogate_groups: Dict[str, object], metric: str = 'harmsim', colors: List[str] | None = None, figsize: tuple = (11, 6), title: str | None = None, show: bool = True) → Figure[source]#

Plot metric distributions for real data vs. surrogate conditions.

Computes an independent t-test between the real group and each surrogate group, and annotates significant differences (p < 0.05) with an asterisk in the legend.

Parameters:

  • real_group (BiotunerGroup) – Original data group (analysis pipeline already computed).

  • surrogate_groups (dict) – {label: BiotunerGroup} for each surrogate condition.

  • metric (str, default=’harmsim’) – Metric column to plot (must exist in every group’s summary).

  • colors (list of str, optional) – One color per condition (real first, then surrogates in dict order). Defaults to a preset palette.

  • figsize (tuple, default=(11, 6)) – Figure size.

  • title (str, optional) – Custom figure title. Defaults to a descriptive auto-title.

  • show (bool, default=True) – Call plt.show() at the end.

Returns:

fig (matplotlib.Figure)

Raises:

ValueError – If metric is not found in any group’s summary.

Contents