Learning-FlexibilityProject

Analysis code for studying temporal coordination between CA1, mPFC, and VTA dopamine neurons during rapid rule switching in a W-track task. This repository combines MATLAB analysis pipelines with Python/CEBRA workflows for neural manifold learning, visualization, and decoding.

Highlights

• Behavioral rule-switch analysis on trial and rule-block timescales.
• Neural embedding and decoding workflows using CEBRA.
• MATLAB pipelines for preprocessing, behavior, LFP, spike, replay, and visualization analyses.
• Python modules and notebooks for reproducible multi-session neural manifold analysis.

Repository Layout

Learning-FlexibilityProject/
├── MATLAB/
│   ├── Preprocessing/
│   ├── Behavior/
│   ├── LFPAnalysis/
│   ├── SpikeAnalysis/
│   ├── Scripts/
│   └── plot/
├── Python/
│   ├── src/cebra_analysis/
│   ├── notebooks/
│   └── requirements.txt
└── README.md

Requirements

• MATLAB (recommended: R2021b or newer).
• Python 3.9+.
• Python dependencies listed in Python/requirements.txt.

Install Python dependencies:

pip install -r Python/requirements.txt

Note: Python/requirements.txt currently includes some standard-library module names (pathlib, math, pickle, random). If pip reports errors for those entries, remove/comment them locally and install the remaining packages.

Setup

1. Clone and enter the repository:

git clone https://github.com/MingxinDing/Learning-FlexibilityProject.git
cd Learning-FlexibilityProject

2. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate

3. Install dependencies:

pip install -r Python/requirements.txt

4. Make Python package imports available:

export PYTHONPATH="$PWD/Python/src:$PYTHONPATH"

In notebooks, you can alternatively use:

import sys
from pathlib import Path
sys.path.append(str(Path("../src")))

Data Layout and Paths

Raw data is not bundled with this repository.

The Python loader expects session files in the directory defined by RAW_DIR in Python/src/cebra_analysis/config.py:

• RAW_DIR / "Data" for input data
• RAW_DIR / "Model" for saved models
• RAW_DIR / "Embedding" for saved embeddings
• RAW_DIR / "Figure" for figures

Default root in code:

RAW_DIR = Path("/Users/mingxinding/Data/RuleSwitch")

Update RAW_DIR in Python/src/cebra_analysis/config.py to match your local machine.

Expected per-session data files (load_session(animal, day)):

• {animal}data_neural{day:02d}.mat
• {animal}data_behavior{day:02d}.csv
• {animal}data_cellinfo{day:02d}.csv

Behavior tables used in Python workflows should include columns used by filtering/labeling code, including:

• trial
• perf
• rule
• traj
• reward
• bin

Python Quickstart (CEBRA Workflow)

This example loads one session, selects a training subset, trains a CEBRA model, and saves both model and embeddings.

import numpy as np
from cebra_analysis.load_data import load_session
from cebra_analysis.compute_subset import compute_subset
from cebra_analysis.training import build_model, save_model
from cebra_analysis.embedding import save_embedding

animal, day = "TH155", 15
area = "PFC"

neural, behavior, cellinfo = load_session(animal, day)

# Select trials by performance/rule/reward criteria.
train_mask = compute_subset(behavior, pct_threshold=60, rule=2, reward=1)
cell_mask = cellinfo["area"] == area

neural_train = neural[train_mask.to_numpy(), :][:, cell_mask.to_numpy()]
label_train = behavior.loc[train_mask, ["traj", "rule", "bin"]].to_numpy()

model = build_model(max_iterations=1000, batch_size=2048)
model.fit(neural_train, label_train)

save_model(model, f"{animal}_day{day:02d}_{area}_demo.pkl")

embedding = model.transform(neural_train)
save_embedding(embedding, f"{animal}_day{day:02d}_{area}_demo_embedding.pkl")

Related Python interfaces:

• cebra_analysis.load_data.load_session
• cebra_analysis.compute_subset.compute_subset
• cebra_analysis.training.build_model
• cebra_analysis.training.save_model
• cebra_analysis.training.load_model
• cebra_analysis.embedding.save_embedding
• cebra_analysis.embedding.load_embedding
• cebra_analysis.plotting.plot_rule
• cebra_analysis.plotting.plot_trajectory
• cebra_analysis.decode.decoding_class
• cebra_analysis.decode.decoding_reg

Notebook Workflows

• Python/notebooks/CEBRA_training_multianimal.ipynb
  • Loads multi-animal sessions.
  • Applies subset selection criteria.
  • Trains multi-session CEBRA models.
  • Compares single-animal vs multi-animal embeddings.
• Python/notebooks/ruleswitch_cebra_run_multisession.ipynb
  • End-to-end exploratory analysis notebook for rule-switching manifolds.
  • Includes embedding analyses, decoding, and transition-related analyses.

MATLAB Workflow Overview

MATLAB analysis is organized by stage/module rather than a single entry script:

• MATLAB/Preprocessing/: session-specific preprocessing and trajectory extraction.
• MATLAB/Behavior/: behavior/performance quantification and rule-switch summaries.
• MATLAB/LFPAnalysis/: theta, coherence, cross-frequency coupling, SWR analyses.
• MATLAB/SpikeAnalysis/: firing dynamics, remapping, decoding, replay analyses.
• MATLAB/Scripts/ and MATLAB/plot/: summary scripts and figure generation.

Representative scripts include:

• MATLAB/Behavior/PerformanceSummary.m
• MATLAB/Scripts/ICA_summary.m
• MATLAB/SpikeAnalysis/PlaceFieldRemapping.m
• MATLAB/SpikeAnalysis/Replay/replay_summary.m

Outputs

Output locations are controlled in Python/src/cebra_analysis/config.py:

• Models: MODEL_DIR = RAW_DIR / "Model"
• Embeddings: EMBEDDING_DIR = RAW_DIR / "Embedding"
• Figures: FIGURE_DIR = RAW_DIR / "Figure"

MATLAB outputs are generated by individual scripts and may vary by workflow and local configuration.

Troubleshooting

• Path errors:
  • Confirm RAW_DIR in Python/src/cebra_analysis/config.py points to your local data root.
• Session loading mismatch:
  • load_session raises ValueError when neural rows and behavior rows differ.
  • Verify matching session files and preprocessing consistency.
• Cell filtering issues:
  • Ensure cellinfo includes an area column with labels such as PFC, CA1, or VTA.
• Missing behavior columns:
  • Verify required columns exist (trial, perf, rule, traj, reward, bin).

Contributing

Contributions from lab collaborators are welcome.

• Open an issue for bugs, reproducibility gaps, or documentation updates.
• Submit pull requests with a clear description of data assumptions and expected outputs.
• Keep analysis scripts explicit about session/day/animal parameters for reproducibility.

Citation and Contact

• This repository currently does not include a LICENSE or CITATION.cff file.
• For citation guidance, manuscript linkage, or collaboration requests, contact the repository owner via GitHub: https://github.com/MingxinDing