Overview

CBASS stands for Clustering Band-limited Activity by State and Spectro-temporal features. It is a method designed to detect recurring spatio-temporal motifs in multi-channel time series. Motifs must have energy in a specified frequency band and their occurence must increase during specific epochs of the recording (i.e. state). The method was originally developed to analyze multichannel Local Field Potentials but can be applied to any time series in principle. A detailed description of the algorithm can be found in the wiki

Code organization

CBASS is implemented in Matlab and Python. Each implementation is contained in a dedicated folder. The code is organized similarly for both and is subdived in 2 main folders:

1. Demo contains script showing exemples of how to run CBASS. These scripts are meant to be edited and modified to the convenience of the user. For the python implementation, the demo is presented in the form of a single Jupyter notebook under the name CBASS_demo.ipynb
2. Pipeline contains the core functions implementing CBASS as well as a number of utilities. This part of the code is meant to be copied and edited by users wishing to modify the method or reuse some of its part.

The matlab implementation has an additional folder Figures containing scripts generating the figures shown in the wiki. These script operate on test data that can be downloaded here.

Link to download example data

The example data can be downloaded from OSF here

Requirements

Matlab

The method has been developed primarily in Matlab 2018b. It should work on any posterior version. Matlab can be downloaded here.

Python

The method has been developed with Python 3.9.7, but the current CBASS implementation has been tested with Python versions 3.7 or newer. For easier setup, we strongly recommend the use of Conda to manage packages. For instructions on how to setup the conda enviroment, see the instructions below.

Getting started

Matlab

1. Make a copy of the CBASS directory and add it to your Matlab path addpath(genpath( path_to_CBASS )).
2. The function CBASS_Main_DetectEvents encapsulate the whole pipeline. A Demonstration of how to run CBASS_Main_DetectEvents can be found in the demo script CBASS_Call_Main__Template.m in the Demo folder. Make a copy of this script and modify it to load your data and reflect your local path.
3. The source code for CBASS_Main_DetectEvents can be found in the Pipeline folder. The help section gives a detailed description its input, output and of the subfunctions implementing the different levels of the pipeline. Subfunctions also have a detailed help. Read and hack as needed.

Python

Install the packages listed in the Conda enviroment description below. We recommend the use of JupyterLab for iteractive use. Check JupyterLab's documentation for installation and quickstart instructions.

Setting up conda environment for optional plot

Replicating our environment

Generating PHATE or UMAP plots of the intermediary steps of CBASS requires to set up miniconda together with python 3.7 or newer. Once miniconda is installed one need to set up an environment with the name gammaBouts_env. This can be done with the following steps:

1. The conda environment definition is in gammaBouts_env.yml. To replicate this environment, do the following:

conda env create --name gammaBouts_env --file gammaBouts_env.yml

Further information about replicating the environment can be found at the conda website.

2. Activate the environment:

• Windows: conda activate gammaBouts_env
• Linux/Mac: source activate gammaBouts_env

Create your own Conda environment

Replicating a conda environment can be challenging. To work around these difficulties, a minimally functional conda environment can be created with the following steps:

1. Create an enviroment with python 3.9

conda create --name gammaBouts_env python=3.9

2. Activate your gammaBouts_env environment

conda activate gammaBouts_env

3. Install key packages using the follwing commands

conda install -c conda-forge umap-learn
conda install -c anaconda matplotlib
conda install -c bioconda scprep
conda install -c bioconda phate

4. Needed for the python version of CBASS

conda install h5py
conda install -c anaconda networkx
conda install pywavelets
conda install -c conda-forge statsmodels
conda install -c conda-forge python-louvain