behavelet 0.0.2
behavelet: a wavelet transform for mapping behavior
License: Apache 2.0

behavelet: a wavelet transform for mapping behavior
============
<p align="center">
<img src="https://github.com/jgraving/behavelet/blob/master/assets/wavelet.png" max-height:256px>
</p>

behavelet is a Python implementation of the normalized Morlet wavelet transform for behavioral mapping from [Berman et al. (2014)](https://doi.org/10.1098/rsif.2014.0672).

It runs on the CPU using numpy and multiprocessing or on the GPU using [CuPy](https://github.com/cupy/cupy).

This code was adapted to Python using [the original MotionMapper code](https://github.com/gordonberman/MotionMapper) from Gordon Berman et al.

Quick Start
------------
Here is an example of how to use behavelet on the CPU with a randomly generated dataset:
```python
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:
```python
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](https://github.com/cupy/cupy):
```python
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:

[![DOI](https://zenodo.org/badge/204273245.svg)](https://zenodo.org/badge/latestdoi/204273245)

      @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)](https://doi.org/10.1098/rsif.2014.0672):

    @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:
```bash
pip install behavelet
```

Install the development version with pip:
```bash
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:
```python
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](https://github.com/cupy/cupy#installation).

Development
-------------
Please submit bugs or feature requests to the [GitHub issue tracker](https://github.com/jgraving/behavelet/issues/new). 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](https://github.com/cupy/cupy), such as installing CUDA or other dependencies, then please direct issues to their development team.

Contributors
------------
behavelet was developed by [Jake Graving](https://github.com/jgraving), and is still being actively developed. Public contributions are welcome. If you wish to contribute, please [fork the repository](https://help.github.com/en/articles/fork-a-repo) to make your modifications and [submit a pull request](https://help.github.com/en/articles/creating-a-pull-request-from-a-fork).

License
------------
Released under a Apache 2.0 License. See [LICENSE](https://github.com/jgraving/behavelet/blob/master/LICENSE) for details.