The fast Continuous Wavelet Transform (fCWT)

The fast Continuous Wavelet Transform (fCWT) is a highly optimized C++ library for very fast calculation of the CWT in C++, Matlab, and Python.

fCWT has been featured on the January 2022 cover of NATURE Computational Science. In this article, fCWT is compared against eight competitor algorithms, tested on noise resistance and validated on synthetic electroencephalography and in vivo extracellular local field potential data.

Please cite our research paper using the sidebar button when using fCWT in your research project.

Arts, L.P.A., van den Broek, E.L. The fast continuous wavelet transformation (fCWT) for real-time, high-quality, noise-resistant time–frequency analysis. Nat Comput Sci 2, 47–58 (2022). https://doi.org/10.1038/s43588-021-00183-z

UPDATE (12-01-2023)

New version available:

fCWT can be seamlessly used in Python (see Jupyter Notebook)
Interface upgrade: Use frequencies instead of scales and octaves!
Fixed small memory allignment bugs

Features

Calculating CWT 34-120x faster than all competitors*
Very high time-frequency resolution (i.e., it does not rely on wavelet estimation)
Real-time CWT for signals having sample frequencies of up to 200kHz
Applicable in many applications ranging from audio and speech to engine vibration analysis
Easy Python integration via pip
Easy MATLAB integration via MEX-files

|fCWT for real-time audio and speech analysis |fCWT for high-resolution in-vivo Neuropixel data analysis | |:--------------------------------------------------------------:|:--------------------------------------------------------------:| |<img src="https://github.com/fastlib/fCWT/blob/main/img/audio.png" alt="fcwtaudio" width="400"/>|<img src="https://github.com/fastlib/fCWT/blob/main/img/eeg.png" alt="fcwteeg" width="400"/>| |fCWT for real-time Electroencephalography (EEG) analysis |fCWT for real-time engine diagnostics | |<img src="https://github.com/fastlib/fCWT/blob/main/img/eeg2.png" alt="fcwteeg2" width="400"/>|<img src="https://github.com/fastlib/fCWT/blob/main/img/engine.png" alt="fcwtengine" width="400"/>|

*Based on C++ performance. fCWT is the fastest CWT library in C++, Python and Matlab! Please see the benchmark section for more details. Raise an issue if you found a new/faster implementation. I will try to add it to benchmark!

Quickstart

fCWT's implementation can be used to accelerate your C++, Python, and Matlab projects! Build the C++ library to achieve the highest efficiency or use the Matlab and Python packages to maximize integration possibilities.

Python

Install the Python package using pip:

$ pip install fcwt

or if you want to install from source:

$ git clone https://github.com/fastlib/fCWT.git
$ cd fCWT
$ pip install .

See this Jupyter Notebook for documentation.

Matlab

Build MEX-files from source:

$ git clone https://github.com/fastlib/fCWT.git
$ cd fCWT
$ mkdir -p build
$ cd build
$ cmake ../ -DBUILD_MATLAB=ON
$ make

Two .mex files should now have been created in the MATLAB folder. Run the example.mlx live script to see how to use fCWT in Matlab. fCWT has been tested in R2022b on an Intel Apple Macbook Pro.

C++

Build fCWT from source:

$ git clone https://github.com/fastlib/fCWT.git
$ cd fCWT
$ mkdir -p build
$ cd build
$ cmake ../ [-DBUILD_BENCHMARK=ON|OFF]
$ make 
$ sudo make install

See the Installation section for more details about building fCWT from source for both UNIX and Windows systems.

Benchmark

Columns are formatted as X-Y, where X is signal length in samples and Y the number of frequencies. The benchmark has been performed on a MacBook Pro 2019 having a 2,3 GHz Intel Core i9 4.5 Ghz Boost, 16 GB 2400 MHz DDR4. See the 'Usage: Benchmark' section for more details about the C++ benchmark. See the Benchmark Notebook for the fCWT Python benchmark.

| Implementation | 10k-300 | 10k-3000 | 100k-300 | 100k-3000 | Speedup factor | |-----------------------|---------|----------|----------|-----------|----------------| | fCWT (C++) | 0.005s | 0.04s | 0.03s | 0.32s | - | | fCWT (Python) | 0.011s | 0.089s | 0.074s | 0.66s | - | | fCWT (Matlab) | 0.072s | 0.44s | 0.17s | 1.55s | - | | | | | | | | | [CCWT] (Python) | 0.019s | 0.11s | 0.15s | 3.40s | 10.63x | | [PyWavelets] (Python) | 0.10s | 1.17s | 1.06s | 12.69s | 34.29x | | Matlab | 0.75s | 0.86s | 1.06s | 13.26s | 35.85x | | [SsqueezePy] (Python) | 0.04s | 0.43s | 1.16s | 17.76s | 48.00x | | SciPy (Python) | 0.19s | 1.82s | 2.11s | 18.70s | 50.54x | | Rwave (C) | 0.18s | 1.84s | 2.28s | 23.22s | 62.75x | | Mathematica | - | - | - | 27.83s | 75.20x | | Wavelib (C++) | 0.25s | 2.55s | 4.85s | 45.04s | 121.72x |

Python Example

import fcwt
import numpy as np
import matplotlib.pyplot as plt

#Initialize
fs = 1000
n = fs*100 #100 seconds
ts = np.arange(n)

#Generate linear chirp
signal = np.sin(2*np.pi*((1+(20*ts)/n)*(ts/fs)))

f0 = 1 #lowest frequency
f1 = 101 #highest frequency
fn = 200 #number of frequencies

#Calculate CWT without plotting...
freqs, out = fcwt.cwt(signal, fs, f0, f1, fn)

#... or calculate and plot CWT
fcwt.plot(signal, fs, f0=f0, f1=f1, fn=fn)

Output:

C++ Example

#include <iostream>
#include <vector>
#include <math.h>
#include <fcwt.h>

int main(int argc, char * argv[]) {
    
    int n = 100000; //signal length
    const int fs = 1000; //sampling frequency
    float twopi = 2.0*3.1415;
    
    //3000 frequencies spread logartihmically between 1 and 32 Hz
    const float f0 = 1;
    const float f1 = 32;
    const int fn = 3000;

    //Define number of threads for multithreaded use
    const int nthreads = 8;

    //input: n real numbers
    std::vector<float> sig(n);
    
    //output: n x scales
    std::vector<complex<float>> tfm(n*fn);
    
    //initialize with 1 Hz cosine wave
    for(auto& el : sig) {
        el = cos(twopi*((float)(&el - &sig[0])/(float)fs));
    }
    
    //Create a wavelet object
    Wavelet *wavelet;
    
    //Initialize a Morlet wavelet having sigma=2.0;
    Morlet morl(2.0f);
    wavelet = &morl;

    //Create the continuous wavelet transform object
    //constructor(wavelet, nthreads, optplan)
    //
    //Arguments
    //wavelet   - pointer to wavelet object
    //nthreads  - number of threads to use
    //optplan   - use FFTW optimization plans if true
    //normalization - take extra time to normalize time-frequency matrix
    FCWT fcwt(wavelet, nthreads, true, false);

    //Generate frequencies
    //constructor(wavelet, dist, fs, f0, f1, fn)
    //
    //Arguments
    //wavelet   - pointer to wavelet object
    //dist      - FCWT_LOGSCALES | FCWT_LINFREQS for logarithmic or linear distribution frequency range
    //fs        - sample frequency
    //f0        - beginning of frequency range
    //f1        - end of frequency range
    //fn        - number of wavelets to generate across frequency range
    Scales scs(wavelet, FCWT_LINFREQS, fs, f0, f1, fn);

    //Perform a CWT
    //cwt(input, length, output, scales)
    //
    //Arguments:
    //input     - floating pointer to input array
    //length    - integer signal length
    //output    - floating pointer to output array
    //scales    - pointer to scales object
    fcwt.cwt(&sig[0], n, &tfm[0], &scs);
        
    return 0;
}

Installation

Dependencies

[Cmake] >=3.10
C++17 compiler ([GCC] 10+, [Clang] or [Microsoft Visual C++][Visual_Studio] 15.7+);
[FFTW] >=3.3 (if you choose to use own FFTW installation)
[OpenMP] >=5

fCWT has been tested on Mac OSX Mojave 10.14.5, Big Sur 11.6 (both on Intel and Apple Silicon), Windows 10, and Ubutnu 20.04. Please raise an issue if you experience issues running fCWT on these systems! We are working very hard on getting fCWT to run on as many platforms as possible. The benchmark has been performed on a MacBook Pro 2019 having a 2,3 GHz Intel Core i9, 16 GB 2400 MHz DDR4.

Build time settings

Settings that may be specified at build time by using [CMake] variables are:

the flag to build a shared library instead of static (default is on);
whether or not you want to use your own FFTW installation*;
whether or not you want to build the BENCHMARK target;
whether or not you want to build the MEX files for MATLAB;
installation directories.

Details:

|CMake variable|Possible values|Default on Unix|Default on Windows| |:-------------|:--------------|:--------------|:-----------------| |The flag to build the shared library|||| |BUILD_SHARED_LIBS|On | Off|On|On| |The flag to use own FFTW installation (e.g., via brew or apt-get)|||| |USE_OWN_FFTW *|On | Off|Off|Off| |The flag to build benchmark target|||| |BUILD_BENCHMARK|On | Off|Off|Off| |The flag to build MATLAB MEX files|||| |BUILD_MATLAB|On | Off|Off|Off| |Installation directories|||| |FCWT_MATLAB_DIR|a path relative to build|"../MATLAB"|"../MATLAB"|

FCWT

Install / Use

README