Fiber_Photometry

A modular Python toolkit and set of Jupyter notebooks for analyzing fiber photometry recordings in rodent behavioral neuroscience paradigms.

---

✨ Overview

This repository implements a flexible pipeline for processing, analyzing, and visualizing fiber photometry data acquired across multiple behavioral contexts (e.g., social defeat, reward training, pinch test). It combines object-oriented Python scripts with notebook-based workflows to enable reproducible and extensible photometry analyses used in the Padilla-Coreano Lab.

---

⚙️ Requirements

• Python ≥ 3.8
• Jupyter Notebook / JupyterLab

---

🚀 Installation

git clone https://github.com/padillacoreanolab/Fiber_Photometry.git
cd Fiber_Photometry
pip install -r requirements.txt
jupyter notebook

---

📁 Repository Structure

Fiber_Photometry/
├── experiment_class.py ← experiment-level container
├── trial_class.py ← trial-level fiber photometry data handler
├── bouts_extension.py ← methods for extracting and analyzing behavioral bouts
│
├── Social_Defeat/ ← example Jupyter notebooks for the social defeat paradigm
├── Reward_Training-Competition/ ← example notebooks for reward vs competition experiments
├── Hab_Dishab/
├── Home_Cage/
├── Pinch_Test/
├── Social_Pref/
└── DA_avg_exploration/

Each paradigm folder contains example notebooks that instantiate classes from experiment_class.py and trial_class.py, load data, perform preprocessing (downsampling, detrending, ΔF/F or Z-score computation), and generate analysis plots (PSTH, heatmaps, etc).

---

📂 Data Organization and File Structure

All raw photometry recordings are collected using TDT Synapse, which automatically saves each session as its own block folder (TDT tank structure). Each experiment therefore consists of multiple block folders, one per recording.

1. ✅ TDT Block Structure

A typical experiment folder looks like:

<Experiment_Root>/
├── n6-240821-100116/ ← TDT block
│ ├── Streams/ # raw DA (465 nm) & ISOS (405 nm) fiber photometry channels
│ ├── Info/
│ ├── TimeEvents/ # TTLs or task events recorded during acquisition
│ └── ...
├── n7-240821-114717/
├── nn1-250115-052028/
├── nn2-250115-054951/
└── ...

• Folder names follow: <animalID>-<YYMMDD>-<time> (as generated by Synapse).
• Each folder contains binary TDT files which are parsed using our experiment_class.py and trial_class.py.

---

2. 🐭 Behavior-Linked Experiments (e.g., Hab/Dishab, Social Defeat)

Some paradigms include extra behavioral annotations collected outside of Synapse — commonly using BORIS or Ethovision, exported as .csv.
To link behavior to photometry traces, the CSV filename must match the corresponding TDT block folder.

Example:

Hab_Dishab/
├── All/
│ ├── nac/ # Block folders for NAc recordings
│ │ ├── n6-240821-100116/
│ │ ├── n7-240821-114717/
│ │ └── ...
│ └── nac_csvs/ # Behavioral CSVs
│ ├── n6-240821-100116.csv
│ ├── n7-240821-114717.csv
│ └── ...

Convention:

• <region>/ → Raw photometry blocks
• <region>_csvs/ → Matching behavior file for each block

During preprocessing, the Experiment class automatically looks in *_csvs/ for a file with the same name and loads the behavioral timestamps to align with the photometry signal. This enables event-locked PSTHs and bout analyses.

---

📌 Summary of Required Inputs per Recording

Field	Source	File Type	Required?
Photometry Signal	TDT Synapse	Block Folder	✅
TTL Events	Synapse	Stored inside block	✅ (for event-driven experiments)
Behavioral Events	BORIS/others	.csv (matching filename)	✅ for HabDishab, Social Defeat etc.
Region Tracking	Folder Name	nch (nac/, mpfc/, etc.)	✅ needed to route to correct analysis pipeline

---

📥 Adding a New Dataset

To analyze a new set of recordings with this repository:

1. Place all TDT block folders in a directory named after the brain region (e.g., nac/).
2. (If applicable) export your behavioral annotations as .csv and put them in a subfolder named <region>_csvs/.
3. Make sure the CSV filename exactly matches the block folder name.
4. Create a bout definitions dictionary identifying bouts and what they are called in Boris csvs.
5. Point the experiment class to the experiment root:

from experiment_class import Experiment

exp = Experiment(
    experiment_path=".../Hab_Dishab/All",
    region="nac"
)
exp.default_batch_process()
exp.group_extract_manual_annotations(bout_definitions=bout_definitions, first_only = True)
exp.compute_all_da_metrics(use_max_length=False,
                                  max_bout_duration=4, 
                                  mode='standard')