TCAnalysis 1.0

The code base is to use of timeCell python module on Matlab files

Time Cell Analysis project: Python and pybind11/C++ files for analysis and demos.

Overview

This repository contains the Matlab, Python and related files for Time Cell Analysis,

This is from a forthcoming paper:

Synthetic Data Resource and Benchmarks for Time Cell Analysis and Detection Algorithms K. Ananthamurthy and U.S. Bhalla, in preparation.

Description

Time cells are neurons whose activity encodes the time since a reference stimulus. They have been observed in the hippocamal CA1, CA3, and also in entorhinal cortex of rodents (refs). They may encode times of the order of 100ms (Modi et al 2014 eLife ) to 20s (Mau et al 2018 Current Biology).

Several algorithms have been developed to identify time cells from amongst a population of firing neurons. With the advent of large-scale unit recordings using 2-photon Calcium imaging or high-density electrodes, it is important to have reliable ways to identify time cells automatically.

This project has implemented a way to assess the performance of time-cell algorithms. We have done two key things. First, we implemented code to generate synthetic neuronal activity data in which we know the ground truth of which cells are time-cells, and we can control parameters such as noise, background activity, jitter, and hit trial ratio (fraction of trials in which the time cell was active). Second, we implemented and extended published time-cell analysis algorithms. While some of the original published algorithms were in Matlab, we have re-implemented key ones in C++ using the pybind11 libraries to provide a simple Python interface. This gives us considerable improvements in speed and memory efficiency, at the cost of some complexity in the code. The Python functions can also be accessed via Matlab, and we illustrate how this is done.

Functions

All these functions should be run from the cloned repository, TimeCellAnalysis.

Name	Description	Command Line	Location	Language
synthesisDemo.m	Command-line demo, output to file: "synthData-demo.mat". Generates a synthetic 2-P time-cell data file.	$ cd TimeCellAnalysis/rho-matlab/demos $ matlab -nodisplay -nosplash -r "synthesisDemo; quit"	rho-matlab/ demos	Matlab
ti_demo.py	Command-line demo, output to console. Runs Temporal information analysis from Mau et al 2018. Reports TImean, TIboot and TIboth classifications	$ python TcPy/ti_demo.py sampleData/sample_synth_data.mat	TcPy	Python interface and C++ numerics
r2b_demo.py	Command-line demo, output to console. Runs Ridge-to-background analysis from Modi et al 2014. Reports R2Bmean, and R2B bootstrap classifications	$ python TcPy/r2b_demo.py sampleData/sample_synth_data.mat	TcPy	Python interface and C++ numerics
peq_demo.py	Command-line demo, output to console. Runs parametric equation analysis from current study. Reports PEQ threshold classification, and estimates for noise, eventWidth, imprecision and hit trial ratio for dataset.	$ python TcPy/peq_demo.py sampleData/sample_synth_data.mat	TcPy	Python interface and C++ numerics
ground_truth_check.py	Command-line demo, output to console. Uses synthetic data files to assess accuracy of classification by the various Mau and Modi algorithms.	$ python TcPy/ground_druth_check.py sampleData/sample_synth_data.mat	TcPy	Python interface and C++ numerics
benchmark.py	Command-line demo, output to console. Simple time and memory benchmarks for the Mau, Modi, or PEQ algorithms.	$ python TcPy/run_batch_analysis.py sampleData/sample_synth_data.mat	TcPy	Python interface and C++ numerics
run_batch_analysis.py	Command-line production script, output to CSV files. Runs a batch analysis using all methods on a data file. Generates csv files for TI, R2B, PEQ and ground truth classifications.	$ python TcPy/ti_demp.py sampleData/sample_synth_data.mat	TcPy	Python interface and C++ numerics
pyBindMap.py	Provides an interface for Matlab programmers, to the python/C++ functions using two wrapper functions: runTIanalysis and runR2Banalysis	Utility function, not run from command line	TcPy	Python
dodFbF.m	Utility function to convert experimental 2P data output from Suite2P to df by f form.	Utility function, not run from command line	rho-matlab/ CustomFunctions	Matlab

Generating Paper Figures

All these functions should be run from the cloned repository, TimeCellAnalysis/rho-matlab/paperFigures. One first generates the csv files with the output of the time-cell analysis using the function described above: run_batch_analysis.py Subsequent analysis and paper figures are generated using the following functions.

Name	Description	Command Line
paperFiguresSynth.m	Plots all figures estimating algorithm performance for Synthetic Data analysis (Paper Fig. 4, Fig. 5, Fig. 6)	$ matlab -r "papersFiguresSynth.m; quit"
paperFiguresReal.m	Plots all figures estimating algorithm performance for Real Physiology Data analysis (Paper Fig. 7)	$ matlab -r "papersFiguresReal.m; quit"
radialPlotSummary.m	Plots a radial plot aka spider plot for algorithm dependence analysis (Paper Fig. 8), to be used only with Synthetic Data Analysis Outputs	$ matlab -r "radialPlotSummary.m; quit"
paperFiguresSplits.m	For diagnostics: Plots all figures estimating algorithm performance over all the regimes (Unphysiological, Canonical, and Physiological)	$ matlab -r "../src/paperFiguresSplits.m; quit"

Directories:

- TcPy: Time Cell analysis Python demos, pybind11 and example driver 
code from Matlab. Primary Author: U.S. Bhalla
Please see README in TcPy for details on running demos etc.

- rho-matlab: Time Cell analysis Matlab libraries.
Please see README in rho-matlab for details on running demos.
The rho-matlab directory is cloned from 
	https://github.com/ananthamurthy/rho-matlab
	commit number 1f0d765
	In it, the paperFigures submodule is from commit 65b69de
and the author of all the code in it is K. Ananthamurthy.

Installation:

pip install TimeCellAnalysis

Following this command, the actual files will be placed in

~/.local/bin/TimeCellAnalysis

or

git clone TimeCellAnalysis
pip install h5py
pip install pybind11
pip install matplotlib
make

Following this command, the actual files will be placed in

./TimeCellAnalysis

To run the demos from the command line you should navigate to the installation directory and either the TcPy or rho-matlab subdirectories respectively, as indicated in their respective README files.