CaFFlow

CaFFlow is a Python framework for acquisition and analysis of single-, two-photon calcium imaging and experimental subject's behavior data. This project was originally intended to be used for acquisition of video data stream(s) generated by Miniscope miniature fluorescence microscope and subsequent (offline and/or online) analysis of the acquired data. Currently however, it can be used for processing of wider range of frame streams, such as subject's behavior only, batch image/video editing etc.

Limitations

As an open architecture system CaFFlow can be extended to fit various needs, but it's current implementation have certain limitations. Such as:

• ROI shape expected to be more or less circular. Detecting ring-shaped ROIs is not supported.
• ROI expected to be a cell body. Detecting Ca++ transients in dendrites/spines etc. is not supported.
• matching ROIs across recording sessions is not yet supported.
• post-processing of the dF/F traces is not yet implemented.

Repository layout

CaFFlow consist of two main parts - framework-side and user-side scripts. The framework-side part is a self-contained set of Python classes/functions representing building blocks common for all recordings/experiments conducted in a Lab. The user-side part is a set of Python scripts adapted for each experiment. The framework is extended by developer(s), and never changed by user(s); it has a strict set of external dependencies and guarantied backward compatibility.

• examples - examples of the user-side scripts. Each script demonstrate usage of particular set of features provided by the mendouscopy framework.
• gui - framework-side code related to input/output data visualization using GUI-based interaction with user.
• mendouscopy - framework-side code related to analysis of the acquired calcium imaging and behavior data. No GUI-related code here.
• mstools - framework-side GUI applications for video stream(s) preview and recording of video frames generated by Miniscope hardware and/or common video cameras.
• unit_test - scripts for testing readiness of your Python environment to be used with the CaFFlow.
• v10n - a set of user-side scripts used for verification of the whole CaFFlow after major code changes or packages updates etc.

Supported OS

• Windows (primarily).
• Any OS for which Python and all required packages available (optionally).

Installation

Prerequisite software installation

Feel free to skip this section if you already familiar with git/git-lfs/conda.

Make sure you have decent text editor (such as for example Notepad++ ) installed. Download and install a command line interface based git client, such as Git for Windows if you do not already have it installed. The git client software is offered in multiple packages. If you not familiar with git choose the default package (32/64 bit installer type) which is usually offered automatically from the link above. During installation make sure to check Git Large File Storage support checkbox. If you had installed the Notepad++ earlier choose it as the default text editor for the git client. All other options may be left default.

Activate the Git LFS extension.

Windows:

• launch the git client application and run: $ git lfs install

MacOS:

• if you use Homebrew, open terminal and run: $ brew install git-lfs
• if you use MacPorts, open terminal and run: $ port install git-lfs

FreeBSD:

• Open terminal and run: $ pkg install git-lfs && git lfs install

Change directory (cd) to the place where you plan to keep CaFFlow and clone this repository:

$ git clone https://github.com/DenisPolygalov/CaFFlow.git

Download and install Miniconda if you don't have it installed already.

CaFFlow installation

Create and activate new 'Conda environment':

Windows:

Launch 'Anaconda Prompt' from Windows Start Menu and type:

(base)> conda create -n cafflow

(base)> conda activate cafflow

MacOS:

Launch the 'Terminal' application and type:

$ source miniconda3/bin/activate

(base)$ conda create -n cafflow

(base)$ source activate cafflow

Install necessary Python packages (the command syntax is common across Windows/MacOS/FreeBSD):

(cafflow)> conda install opencv numpy pandas scipy tifffile

The set of packages above is sufficient to run analysis without visualization (on a headless server for example) and without GUI-based applications.

For GUI-based applications and video capturing software - please install PyQt and Matplotlib packages:

(cafflow)> conda install pyqt matplotlib

Check video encoding/decoding support by running the examples/sXX_capture_video.py script:

(cafflow)> cd CaFFlow\examples

(cafflow)> python sXX_capture_video.py

and examine it's output. The script will try to capture a chunk of video stream from default video camera (must be connected in advance obviously), encode the video by using whatever codec provided by OpenCV and write encoded video into a file called 'captured_video.[avi|mp4]' located in the same directory. Check if the file was created, and you can play it by using VLC Media Player software for example.

The next step is to test your Python environment:

(cafflow)> cd CaFFlow

(cafflow)> python -m unittest discover unit_test

While running command above you may see warning messages such as "RuntimeWarning: numpy.ufunc size changed, may indicate binary incompatibility." which is caused by numpy package and known to be harmless. Any error messages however indicate problems with your Python environment.

Read Python scripts located in the examples directory, execute them and adjust for your purpose. Note that all example scripts are intended to be executed from inside of the examples directory.