Core functions for analyzing and visualizing data for the sleep project

The codebase contains a mix of functions and classes that work either locally in the Conda environment provided by the environment.yaml file or in Google Colab notebooks.

Installation

Prerequisites

• Conda (Miniconda or Anaconda)
• Python 3.9+

Steps

1. Clone the repository

   git clone https://github.com/GergelyTuri/sleep.git
   cd sleep

2. Create and activate the Conda environment

   conda env create -f environment.yaml
   conda activate sleep

3. Install the package in editable mode

   pip install -e .

4. Install pip-only extras

   pip install -r requirements.txt

Google Colab

The modules under src/colab/ (google_utils.py, google_drive.py) require google.colab and are only usable inside a Colab notebook. They are guarded with a try/except ImportError so they won't break local imports. If you need Google Drive integration in Colab, install the optional dependencies manually:

pip install gspread google-auth

Running Notebooks

jupyter notebook

Running Tests

pytest tests/test_unit.py -v

Scripts

Behavior data processing

scripts/behavior_scripts/process_tdml_behavior_data.py converts BehaviorMate .tdml or .vr files into structured .json output. The output file is written to the same directory as the input. By default sessions whose outputs already exist are skipped; use -o to force regeneration.

# single file
python scripts/behavior_scripts/process_tdml_behavior_data.py -f path/to/file.tdml

# entire directory tree
python scripts/behavior_scripts/process_tdml_behavior_data.py -d path/to/dir

# also load into the SQL database (requires lab3 and DB environment variables)
python scripts/behavior_scripts/process_tdml_behavior_data.py -f file.tdml --sql -g my_group