Preparing IntelliCage data

The toolkit expects IntelliCage export tables to be extracted from the original export zip archives and grouped by cage run. A cage run is one physical cage/group recording session with its own start time. Multiple cage runs can belong to the same experiment, and they do not have to start at the same clock time.

Phase windows

In each analysis script, you define experimental phase windows per subject, not globally. This is important because cage runs can start at different times. Each subject entry should provide one time_window tuple per phase, e.g.:

SUBJECTS = {
    "910200000001000": {
        "group": "Group A",
        "sex": "male",
        "true_id": "A01",
        "date_of_birth": "2025-09-01",
        "corner_assignments": {
            3: 1,
            4: 3},
        "phases": {
            1: {"time_window": ("2026-01-05 06:00:00", "2026-01-08 08:00:00")},
            2: {"time_window": ("2026-01-08 08:00:00", "2026-01-10 08:00:00")}}}}

During load(), the toolkit keeps only animal IDs that are defined in SUBJECTS. This makes the analysis reproducible and prevents accidental analysis of animals that were exported but should not belong to the study.

Practical checklist

Before running an analysis script:

  1. Extract all IntelliCage export ZIP files.

  2. Create one folder per cage run below the experiment data root.

  3. Place each export block’s IntelliCage folder containing Visits.txt and Nosepokes.txt into the corresponding cage-run folder, and name the export-block folders clearly, e.g., Export_Block_1, Export_Block_2, … or Phase1, Phase2, …, or any other readable and unique names that sort alphanumerically in the same order as the chronological order of the IntelliCage exports.

  4. Define all included animals in SUBJECTS or create/load a subject YAML template.

  5. Check that every included subject has a time_window for every required phase.