behavelet: a wavelet transform for mapping behavior

behavelet is a Python implementation of the normalized Morlet wavelet transform for behavioral mapping from Berman et al. (2014).

It runs on the CPU using numpy and multiprocessing or on the GPU using CuPy.

This code was adapted to Python using the original MotionMapper code from Gordon Berman et al.

Quick Start

Here is an example of how to use behavelet on the CPU with a randomly generated dataset:

from behavelet import wavelet_transform
import numpy as np

n_samples = 10000
n_features = 10
X = np.random.normal(size=(n_samples, n_features))

freqs, power, X_new = wavelet_transform(X, n_freqs=25, fsample=100., fmin=1., fmax=50.)

use the n_jobs argument to parallelize the computations across multiple threads:

freqs, power, X_new = wavelet_transform(X, n_freqs=25, fsample=100., fmin=1., fmax=50., n_jobs=-1)

and use the gpu argument to run it on the GPU with CuPy:

freqs, power, X_new = wavelet_transform(X, n_freqs=25, fsample=100., fmin=1., fmax=50., gpu=True)

• freqs is a (n_freqs,) shaped array of the frequencies used for the wavelet transform
• power is a (n_samples,) shaped array with the total power for the wavelet coefficients in each sample
• X_new is a (n_samples, n_freqs*n_features) shaped array of the wavelet coefficients.

Citation

If you use behavelet for your research, please cite our DOI:

  @misc{graving2019behavelet,
        title={behavelet: a wavelet transform for mapping behavior},
        author={Graving, Jacob M},
        month={aug},
        year={2019},
        doi={10.5281/zenodo.3376742},
        url={https://doi.org/10.5281/zenodo.3376742}
        }

for the original description of the normalized Morlet wavelet transform see the paper from Berman et al. (2014):

@article{berman2014mapping,
         title={Mapping the stereotyped behaviour of freely moving fruit flies},
         author={Berman, Gordon J and Choi, Daniel M and Bialek, William and Shaevitz, Joshua W},
         journal={Journal of The Royal Society Interface},
         volume={11},
         number={99},
         pages={20140672},
         year={2014},
         publisher={The Royal Society}
         }

Installation

Install the latest stable version with pip:

pip install behavelet

Install the development version with pip:

pip install git+https://www.github.com/jgraving/behavelet.git

You can also install from within Python rather than using the command line, either from within Jupyter or another IDE, to ensure it is installed in the correct working environment:

import sys
!{sys.executable} -m pip install git+https://www.github.com/jgraving/behavelet.git

If you wish to use the GPU version, you must install CuPy manually.

Development

Please submit bugs or feature requests to the GitHub issue tracker. Please limit reported issues to the behavelet codebase and provide as much detail as you can with a minimal working example if possible.

If you experience problems with CuPy, such as installing CUDA or other dependencies, then please direct issues to their development team.

Contributors

behavelet was developed by Jake Graving, and is still being actively developed. Public contributions are welcome. If you wish to contribute, please fork the repository to make your modifications and submit a pull request.

License

Released under a Apache 2.0 License. See LICENSE for details.