Brain-Inspired AI: Fear Conditioning

This repository contains deep learning experiments that model classical fear conditioning paradigms. The work investigates how visual stimuli associated with pleasant and unpleasant outcomes can be learned by a neural network and analysed from a neuroscience perspective.

The codebase includes training pipelines for regression, quadrant fine-tuning, and conditioning experiments, together with analysis notebooks and helper utilities.

Note: Due to licensing restrictions the IAPS dataset is not distributed with this repository. Pre-trained model checkpoints that rely on the dataset are expected to live under ./savedmodel as described below.

Table of Contents

• Project Structure
• Environment Setup
• Data Preparation
• Key Training Scripts
• Running Experiments
• Analyses and Utilities
• Troubleshooting

Project Structure

.
├── dataloader.py                # Dataset utilities and PyTorch dataloaders
├── train_regression.py          # End-to-end training on raw images
├── train_finetuning.py          # Quadrant-based fine-tuning stage
├── train_conditioning2.py       # Conditioning procedure with Gabor stimuli
├── utils.py                     # Helper functions for logging and evaluation
├── models/                      # Model definitions (VGG variants, attention modules, etc.)
├── data/                        # Expected location of input images and CSV labels
├── torchsampler/                # Custom sampler for imbalanced datasets
├── analysis scripts (*.py/Rmd)  # RSA, SVM, channel activity, manifold visualisations
└── README.md

Environment Setup

1. Python: Python 3.8 or later is recommended.
2. Dependencies: Install the required packages:

   pip install -r requirements.txt

   If a requirements.txt file is unavailable, install the main packages manually (PyTorch, torchvision, numpy, pandas, scikit-image, scikit-learn, matplotlib, seaborn, altair, etc.).
3. GPU Support: The training scripts assume CUDA is available. Update CUDA_VISIBLE_DEVICES in the scripts if a different GPU configuration is required.

Data Preparation

1. Create the expected directory layout inside ./data:

   data/
   ├── <TRAIN_FOLDER>/
   ├── <VAL_FOLDER>/
   ├── <TEST_FOLDER>/
   └── *.csv
   

2. CSV files must contain the image filename (without extension), extension, and corresponding labels/valence scores as used by RegressionDataset in dataloader.py.
3. Place any Gabor patch resources referenced by conditioning experiments under ./data/gabor_patch_full/ or update the command-line arguments accordingly.

Key Training Scripts

train_regression.py

Trains a base regression network from scratch or resumes from a saved checkpoint.

Important arguments:

• --data_dir: Root directory for datasets.
• --TRAIN, --VAL, --TEST: Subdirectories for each split.
• --csv_train, --csv_val, --csv_test: Label CSV files for each split.
• --batch_size, --epoch, --lr: Training hyperparameters.
• --is_fine_tune: Set to True to start from a pre-trained checkpoint specified by --file_name in --model_dir.

Example:

python train_regression.py \
  --data_dir ./data \
  --TRAIN IAPS_split_train --VAL IAPS_split_val --TEST IAPS_split_test \
  --csv_train IAPS_split_train.csv --csv_val IAPS_split_val.csv --csv_test IAPS_split_test.csv \
  --batch_size 10 --lr 1e-4 --model_to_run 6 --model_dir ./savedmodel --is_fine_tune True

train_finetuning.py

Fine-tunes a model using quadrant-processed inputs. It accepts the same arguments as train_regression.py and expects the fine-tune source checkpoint to be in --model_dir.

train_conditioning2.py

Performs the conditioning stage that associates stimuli with Gabor patches. In addition to the standard arguments, specify:

• --gabor_dir1 / --gabor_dir2: Paths to the Gabor images for unpleasant and pleasant stimuli.
• --TRAIN / --TRAIN2: Folder names for each stimulus class.
• --csv_train / --csv_train2: CSV label files for each class.
• --manipulation: Probability of masking the unconditioned stimulus during training.

Example:

python train_conditioning2.py \
  --data_dir ./data \
  --gabor_dir1 ./data/gabor_patch_full/freq20/gabor-gaussian-45-freq20-cont50.png \
  --gabor_dir2 ./data/gabor_patch_full/freq20/gabor-gaussian-135-freq20-cont50.png \
  --TRAIN IAPS_Conditioning_Unpleasant2 --TRAIN2 IAPS_Conditioning_Pleasant2 \
  --csv_train ./data/IAPS_Conditioning_Unpleasant2.csv \
  --csv_train2 ./data/IAPS_Conditioning_Pleasant2.csv \
  --batch_size 10 --lr 1e-4

Running Experiments

1. Regression pre-training: python train_regression.py ...
2. Quadrant fine-tuning (optional): python train_finetuning.py ...
3. Conditioning: python train_conditioning2.py ...
4. Inference / Evaluation: Use the various analysis scripts under the repository root to inspect features, generate RSA plots, or evaluate classification metrics.

Each script logs progress to the console and may generate plots or checkpoint files under the specified --model_dir.

Analyses and Utilities

• Channel_Activity_Extraction.py, Channel_Selectivity_Extraction.py: Inspect CNN activations.
• RSA_Analysis.py, Distance_Analysis.py, Manifold_Visualization.py: Explore representational geometry of learned features.
• SVM_Analysis_*.py: Downstream classification experiments.
• test_gaborpatch_iteration.py, test_gaborpatches.py: Utilities for validating Gabor stimuli processing.

Refer to the inline documentation of each script for detailed usage instructions.

Troubleshooting

• Ensure CSV files match the expected formatting; missing columns or incorrect filenames will raise errors when loading images.
• If GPU memory becomes constrained, adjust the batch size or enable gradient accumulation.
• When experimenting with conditioning, verify that --manipulation is set between 0.0 and 1.0 to represent a probability of masking the unconditioned stimulus.

For questions or contributions, please open an issue or submit a pull request.