Unsupervised discovery of behaviorally relevant brain states in rats playing hide-and-seek

Installation

To reproduce the analysis and play around with the data on your own, you have to install the hidenseek Python package contained in this repository.

Clone the repository:

• git clone https://github.com/bagibence/hidenseek_hmm.git

Enter the project directory:

• cd hidenseek_hmm

Create a conda environment called hidenseek and install the dependencies:

• conda env create -f environment.yml

Activate the environment:

• conda activate hidenseek

Install the ssm package by hand. (I didn't include it in the dependencies because sometimes you have to troubleshoot some errors before being able to install it.)

Install the hidenseek package:

• pip install -e .

Create a jupyter kernel for you environment:

• python -m ipykernel install --user --name hidenseek --display-name "Python (hidenseek)"

Install the ipywidgets extension to see progress bars in JupyterLab:

• jupyter labextension install @jupyter-widgets/jupyterlab-manager

Getting the data

The processed SQLite files (database.db and observing.db) are deposited here. Put these into /data/interim/.

Opening the notebooks

All figures are generated by Jupyter notebooks in the notebooks directory. We are using Jupytext to sync them with .py files. These .py files are then version controlled and contained in this repo.

To open the notebooks, first install the hidenseek package by following the instructions in Installation. By now you should have JupyterLab, Jupytext and its JupyterLab extension installed.

Activate the environment by

• conda activate hidenseek

Open JupyterLab by

• jupyter lab

Then open the .py files by

• Right click - Open with - Notebook

This will open it as a notebook and create a .ipynb file the .py is synced with.

Notes

• I might have forgotten to include some packages in the dependency lists. If so, please let me know.

• If you don't want to create a new conda environment, you can still install the hidenseek package using pip, you just have to take care of the dependencies by hand.

• If your kernel is not called Python (hidenseek), when running notebooks you'll have to select the kernel you installed hidenseek in.

Project structure

Project structure is inspired by Alex Williams's "Cookiecutter For Neural Data Analysis":

├── data               <- Folder containing all data.
│   │
│   ├── raw            <- Sub-folder containing immutable raw data. In this case .mat files
│   │
│   ├── interim        <- Sub-folder containing data cleaned within Matlab, then further organized into SQLite databases.
│   │
│   └── processed      <- Fitted GPFA and HMM models
│    
│
├── matlab   <- Matlab code used for preprocessing the raw data.
│     
│
├── hidenseek   <- Source code for reading and analyzing the data, used by the notebooks.
│   │
│   ├── __init__.py      <- Makes project a Python module
│   ├── db_interface.py  <- ORM mapping for Cell, Trial, and Session objects.
│   ├── db_mixins.py     <- Methods and properties for the above classes.
│   ├── preprocessing.py <- Some code for processing spikes trains.
│   ├── matlab_interface.py               <- Used for generating the database file by notebooks/preprocessing/populate_database.ipynb
│   ├── observing_matlab_interface.py     <- Used for generating the observing database file by notebooks/preprocessing/populate_observing_database.ipynb
│   │
│   |   ... this is where it gets messy ...
│   │
│   ├── util        <- Generally smaller functions that are used often and help with plotting and such.
│   │
│   └── figure_util <- Generally longer code moved out of notebooks, performing whole steps of the analyses, mostly only used in one or a few places.
│
│
├── notebooks          <- Jupyter notebooks for performing the bulk of the analysis.
│   │
│   ├── preprocessing  <- Notebooks for storing data in SQLite databases, running GPFA, runnnig HMM
│   │
│   ├── figures        <- Notebooks for generating the figures in the paper.
│   │
│   └── ... some other notebooks ...
│
├── reports
│   └── figures                <- Generated figures are saved here.
│       └── source_images      <- Images needed for the figures which are not generated by code.
│
│
├── environment.yml    <- Lists dependencies that are (ideally) enough to recreate the environment needed for running the code.
│
├── requirements.txt   <- Lists required python libraries.
│
└── setup.py           <- makes project installable by `pip install -e .`. Also generates config.dotenv and /matlab/data_path.m