pybic

Polyspectral analysis toolkit for Python.

______     ______ _
| ___ \    | ___ (_)
| |_/ /   _| |_/ /_  ___
|  __/ | | | ___ \ |/ __|               v2.1 (c) 2022-2026
| |  | |_| | |_/ / | (__
\_|   \__, \____/|_|\___|              G. Riggs & T. Matheny
       __/ |
      |___/

PyBic is an open-source module specializing in signal processing, with particular emphasis on polyspectral analysis.

The Bic in PyBic refers to bicoherence analysis, which is by far the most common use of the polyspectrum. Explicitly, we use

The bispectrum

B_xyz(f1,f2) = < X(f1)Y(f2)Z(f1+f2)* >,

where x,y,z are time series with corresponding Fourier transforms
X,Y,Z, and <...> denotes averaging in time.

The (squared) bicoherence spectrum

b^2_xyz(f1,f2) =           |B_xyz(f1,f2)|^2
                         --------------------
               ( <|X(f1)Y(f2)|^2> <|Z(f1+f2)|^2> + eps ),

where eps is a small number meant to prevent 0/0 = NaN catastrophe

For more information and references on the history, theory, utility, and implementation of polyspectra, please see our publication in Computer Physics Communications, RiggsKoepkeMatheny2026.

Also check out our GitHub repo and Read the Docs pages!

To run the demo from the shell, use

$ python3 pybic.py

or, alternatively, in Python

import pybic as bic
b = bic.RunDemo()

Additionally, we’ve developed Jupyter notebooks with a guided tour of PyBic and a demonstration of the Plot() function.

Todo

  • Add minimum threshold keyword to PlotBispec() method to mask b^2 below noise floor (none)

  • Add colormap picker in PlotGUI() with SHIFT + c, say (none)

  • Swap out matplotlib widgets for full tkinter GUI =^x (some)

  • Figure out setter functions (some)

  • Configure warnings (none)

  • Implement some kind of check for Raw data! Should eliminate string, etc. (done)

  • Fix colorbar axes overplotting each refresh (done)

  • Fix issue with colorbar labels when calling RefreshGUI() (done)

  • Add buttons and callbacks from Matlab (some)

  • Swap out “dum” variables for more literate ones

  • Comment the code!!! (some)

  • Fix butt-ugly inputs to PlotPointOut children! (done)

  • Flag for base units (maybe not based in time, say)

  • Antialiased option! (none)

  • Bispectrogram (none)

  • Auto-filters! (none)

  • Video output (none)

  • Base units (none)

  • Cross stuff in BicAn.FindMaxInRange() (none)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Functions

ApplyBandpass(x[, fS, f0, fband])

Quick and dirty brickwall bandpass filter.

ApplyCWT(sig[, samprate, sigma, limFreq, ...])

Calculate continuous wavelet transform (CWT) of time-series.

ApplyDetrend(y)

Remove linear trend from data.

ApplyRealBandpass(D, fS, flim, fband[, order])

Butterworth bandpass filter.

ApplySTFT(sig[, samprate, subint, step, ...])

Calculate short-time Fourier transform (STFT) of time-series.

CalcHistVsT(sig[, samprate, subint, step, ...])

Calculate amplitude histogram vs. time of time-series.

DrawSimplex(flim)

Draws simplex for trispectrum.

FileDialog()

Simple file picker dialog.

FlatTopWindow(N)

Flat-top window.

GetBispec(spec[, v, lilguy, j, k, rando])

Estimate local bispectrum and bicoherence of a single (f1,f2) value.

GetBispecBootstrap(spec[, v, lilguy, j, k, ...])

Estimate mean and std dev of bicoherence for single (f1,f2) value.

GetPolySpec(spec, f[, lilguy, rando, v])

Estimate the nth-order polyspectrum/polycoherence spectrum of a given (f1,f2,...,fn) value

HannWindow(N[, q])

Hann window (and all powers of sine).

InstFreqZeroCross(x[, dt, crossType, ...])

Calculates instantaneous frequency from zero crossings.

LoadBar(m, M[, bar_length])

Loading bar animation.

Plot(dats[, strings, color, alpha, marker, ...])

All purpose plotting tool!

PlotLabels(fig, ax[, strings, fsize, ...])

General purpose plot labels.

PlotRHS(x, y, ax[, r_col, ylab, ylim, ...])

Add plot and right-hand side (RHS) label to existing plot.

PlotTimeline(x, y[, t, fig, ax, lw, cmap, ...])

Plot line with color.

PlotTop(x, y, ax[, col, xlab, xlim, fsize, ...])

Add plot and top label to existing plot.

RunDemo()

Demonstration of BicAn.

ScaleToString(scale)

Converts order of magnitude to `metric prefix`_.

SignalGen([fS, tend, Ax, fx, Afx, Ay, fy, ...])

3-oscillator FM signal generator.

SpecToBispec(spec[, v, lilguy])

Estimate auto-bispectrum/-bicoherence spectrum from spectrogram(s).

SpecToCoherence(spec[, lilguy])

Estimate cross-spectrum/-coherence from spectrogram.

SpecToCrossBispec(spec[, v, lilguy])

Estimate cross-bispectrum/-bicoherence spectrum from spectrogram(s).

SpecToTrispec(spec[, v, lilguy])

Estimate auto-trispectrum/-tricoherence spectrum from spectrogram(s).

TestSignal(whatsig[, tend, noisy, fS, f1, f2])

Provides various signals for bispectral analysis.

WhittakerShannon(x, Ninterp[, fS, T0, interp])

Whittaker-Shannon interpolation.

arrmin(arr)

Matlab-esque min().

bin_mat(n)

Creates array of all combinations of [+/-1, +/-1, ...].

boxcar_ave(x, N)

Smooths data, attempts to return correct amplitudes.

dphase_dt(z)

Returns gradient of unwrapped phase.

nRandSumLessThanUnity(n)

Outputs n numbers whose sum is < 1.

Classes

BicAn(inData, **kwargs)

Main class of pybic module, i.e., Bicoherence Analyzer.