README.txt
----------

Title: Behavioral and Calcium Imaging Video Synchronization and Export

Author: Marcelo D. Mendonça
Institution: Champalimaud Foundation
Date: August 30, 2017 (data); June 2025 (documentation)

Overview:
---------
This MATLAB script generates synchronized composite videos aligning side-view behavioral recordings with ΔF/F calcium imaging data acquired using a miniature microscope (Inscopix). It processes data from two experimental conditions (baseline and drug/lesion), aligning video frames to calcium imaging timestamps using accelerometer and centroid metadata, then exports composite videos suitable for analysis or publication.

Structure:
----------
The script contains two main blocks:

1. **Baseline Condition ("BS")**
   - Loads preprocessed calcium imaging data.
   - Aligns Inscopix timestamps with behavioral video using accelerometer logs and centroid timestamps.
   - Extracts a temporally matched window of side camera video.
   - Upsamples both calcium and behavioral videos to achieve temporal alignment.
   - Concatenates behavior (top), white spacer, and calcium activity (bottom) into a single movie.
   - Exports video as `BS_Newbg.avi`.

2. **Drug/Lesion Condition ("LD")**
   - Repeats the above steps for the LD session.
   - Outputs synchronized video as `Dysk_OptimalBG.avi`.

Inputs:
-------
- Calcium imaging `.mat` files containing variable `Y` (ΔF/F values):

- Accelerometer CSV files with camera and Inscopix timestamps:

- Top and side camera centroid timestamp logs:

- Behavioral side-view AVI videos:

Outputs:
--------
- `BS_Newbg.avi`: Composite video of baseline behavior and calcium activity.
- `Dysk_OptimalBG.avi`: Composite video of drug/lesion behavior and calcium activity.

Video Layout:
-------------
Top: Grayscale side camera video of freely behaving mouse  
Middle: White separator (20 pixels)  
Bottom: Grayscale ΔF/F calcium imaging (rescaled to 8-bit)

Dependencies:
-------------
- MATLAB R2018a or later (tested)
- Image Processing Toolbox
- Video Processing Toolbox

Instructions:
-------------
1. Ensure all `.mat`, `.csv`, and `.avi` files are located in the paths specified within the script.
2. Run the script in MATLAB. It will automatically generate both composite videos.
3. Review output `.avi` files using standard video players or frame-by-frame analysis tools.

Citation:
---------
If you use or adapt this script for publication, please cite:

Alcacer C. et al. (2025). Abnormal hyperactivity of specific striatal ensembles encodes distinct dyskinetic behaviors revealed by high-resolution clustering. Cell Reports.