ROI Analysis — Structural Inference Paper
==========================================
Author: Georgios Tertikas

Pipeline overview
-----------------
FSL first/second-level modelling
  → Python ROI extraction  (Python_extraction/)
      → R statistics & visualisation  (R_stats/)

The Python scripts call FSL (fslmerge, fslmeants) and AFNI (3dresample).
They require FSL and AFNI to be available on the system PATH.
Input data live on the MRI analysis drive:
  /mnt/d/Struct_learning_fMRI/MRI_main/Imaging/Second_level/

ROI masks (.nii.gz) are in the original project folder:
  UCL_file_structure/.../ROI_analysis/Masks/


Python extraction scripts
-------------------------

ROI_extraction.py
  Purpose : Extract mean z-stat signal per participant from across-task GLM
            cope maps (stable/novel/outdated/irrelevant > irrelevant contrasts).
  Dataset : RS_across_MB_new  (across-MB suppression GLM)
  Masks   : a-priori ROI masks (hippocampus, mOFC, FP, amFC)
  Output  : RS_across_MB_new/combined_copes_dataset.txt
  Feeds   : Across_RS_ROI_comparison.R  (Figure 3)

ROI_extraction_beta_time_course.py
  Purpose : Extract parameter-estimate (beta) values across the SB-1 / SB+1 /
            SB+2 time-course from the between-MB GLM. Uses fslmerge to stack pe
            maps across participants, then fslmeants within each ROI mask.
  Dataset : RS_between_MB_all
  Masks   : Beta_extraction_masks/Time_course  AND  Significant_masks
  Output  : Mask_analysis/Time_course/RS_between_MB_all/combined_pe_dataset.txt
  Feeds   : Beta_time_course_between_all.R  (Figures 4 & 5 *_sep.jpg plots)

ROI_extraction_beta_perf.py
  Purpose : Splits participants into high vs low performers (median-split on
            optimum performance) using hardcoded index lists (grouping_indices_lh
            / grouping_indices_sh), then extracts betas separately for each
            group across three mask sets.
  Dataset : RS_between_MB_all
  Masks   : Beta_extraction_masks/Perf  |  Time_course  |  Significant_masks
  Output  : Performance_analysis/Mask_analysis/.../combined_group_1/2_pe_dataset.txt
  Feeds   : Correlation_with_opt_perf_and mediation_analysis.R  (Figure 6)

TCPE_preprocessing.py
  Purpose : Preprocessing step run before ROI_extraction_beta_time_course.py —
            resamples and aligns masks to the subject-level PE map space.
  Run before: ROI_extraction_beta_time_course.py

TCPE_preprocessing_perf_ROI.py
  Purpose : Preprocessing step before ROI_extraction_beta_perf.py —
            same mask resampling but for the performance-split ROI analysis.
  Run before: ROI_extraction_beta_perf.py


R visualisation scripts
-----------------------

Across_RS_ROI_comparison.R
  Purpose : Reads combined_copes_dataset.txt from the across-task GLM and
            plots mean ROI signal per condition (Novel, Outdated, Stable,
            Irrelevant) with paired t-tests.
  Outputs : NEW_FP.jpg, NEW_hip.jpg, OLD_FP.jpg, OLD_hip.jpg,
            Irr_FP.jpg, Irr_hip.jpg, OLD_Irr_FP.jpg, OLD_Irr_Hip.jpg
  Figure  : Figure 3

Beta_time_course_between_all.R
  Purpose : Reads combined_pe_dataset.txt from the between-MB time-course
            extraction and plots mean beta ± SEM per ROI at SB-1, SB+1, SB+2
            with Bonferroni-corrected paired t-tests.
  Outputs : Novel_Irr_CB1_amFC_sep.jpg, Novel_Irr_CB2_mOFC_sep.jpg,
            Novel_Irr_across_mask_amFC_sep.jpg, Novel_Irr_across_mask_hip_sep.jpg,
            Old_Irr_CB2_amFC_sep.jpg, Old_Irr_across_hip_sep.jpg,
            New_Irr_across_Hip_sep.jpg, New_Irr_across_vmPFC_sep.jpg,
            Stable_Irr_across_mOFC_sep.jpg
  Figures : Figures 4 & 5

Between_RS_all_ROI_comparison.R
  Purpose : Reads both combined_copes_dataset.txt and combined_pe_dataset.txt
            from RS_between_MB_all and runs the between-changepoint contrast
            comparisons (outdated SB+1 vs SB-1; novel SB+1 vs SB+2 migration).
  Outputs : FP/Hippocampus before-after changepoint plots
            (SB+1 vs SB+2 t-tests: FP t(48)=−2.22 p=.031;
             Hippocampus t(48)=3.50 p=.002)
  Figure  : Figure 5

Correlation_with_opt_perf_and mediation_analysis.R
  Purpose : Correlates per-participant beta estimates (high vs low performer
            groups) with optimum performance and runs mediation analyses.
  Outputs : Cor_perf_New_CB+1_amFC.jpg, Cor_perf_New_CB+1_hip.jpg,
            Cor_perf_Old_CB+2_hip.jpg, Cor_perf_Old_CB+2_mOFC.jpg
  Figure  : Figure 6


Scripts NOT included (excluded from paper)
------------------------------------------
ROI_extraction_feed.py       — feedback GLM (not reported)
ROI_extraction_all.py        — broader exploratory mask set
Rock_gem_RS_ROI_comparison.R — pilot stimulus set (not in main paper)
Rock_gem_beta_ROI.R          — pilot
Between_RS_ROI_comparison.R  — older RS_between_MB dataset (superseded by _all)
Across_RS_beta_ROI.R         — pe duplicate of across-task (not used for figures)
Trial.R                      — test/scratch script