yguo29/locanmf

Pytorch implementation of LocaNMF

LocaNMF

LocaNMF (Localized semi-Nonnegative Matrix Factorization) can efficiently decompose widefield video data and allows user to directly compare activity across multiple mice by outputting mouse-specific localized functional regions. LocaNMF uses a fast low-rank version of Hierarchical Alternating Least Squares (HALS), and outputs components that are significantly more interpretable than traditional NMF or SVD-based techniques. Read more about this method and the results it provides in our bioRxiv : Saxena et al., 2019!

It is built on top of PyTorch, written in Python and C++, and is capable to run on either CPU or Nvidia CUDA-enabled GPU. To run LocaNMF on Nvidia GPU, a Nvidia CUDA-enabled GPU is required and the latest version Nvidia Driver (version > 418.x) is required to be properly installed before installing LocaNMF software.

Install

It is recommended to use conda to manage the dependencies for LocaNMF in it's own Python environment. First, download and install conda. Verify conda installation by executing the following scripts. A list of base environment packages will be displayed.

conda list

Create a new environment for LocaNMF and install LocaNMF software and all of its dependencies.

conda create -n locanmf python=3.6 locanmf -c ss5513 -c pytorch

Use LocaNMF

Activate locanmf conda environment.

conda activate locanmf

To test the proper installation of LocaNMF software, execute the following script.

python
from locanmf import LocaNMF
LocaNMF.version()

The following output will be displayed. It implies that LocaNMF and its dependencies have been properly installed.

python
Python 3.6.8 |Anaconda, Inc.| (default, Dec 30 2018, 01:22:34) 
[GCC 7.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from  locanmf import LocaNMF
>>> LocaNMF.version()
version = 1.1
>>>

Please download the demo folder in this repository to your computer and walk through the demo_simulation.ipynb notebook to try out the software.

To run the notebook, in terminal, change directory to the downloaded demo folder, then execute,

jupyter-lab &

to start jupyter-lab server. In the pop-out web browser, double-click the notebook to open it. The code is editable and can be run cell by cell by pressing "shift + enter".

LocaNMF documentation is also available.

Preprocessing

Check out MATLAB code to preprocess your data for LocaNMF.