Sovereign 8s.is mirror of standardgalactic/avatarRT_analysis
  • Jupyter Notebook 65.3%
  • Python 33.7%
  • Shell 1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-04-21 14:15:39 -04:00
MRAE@5ba7729f1c updated readme and consistency 2026-04-20 20:59:21 -04:00
preprocessing updated readme and consistency 2026-04-20 20:59:21 -04:00
results adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
slurm_scripts adding final analysis and plotting 2025-02-03 13:43:37 -05:00
.gitignore removed unwanted files and notebook; updated .gitignore 2026-04-20 21:08:25 -04:00
.gitmodules updated readme and consistency 2026-04-20 20:59:21 -04:00
analysis_helpers.py updated readme and consistency 2026-04-20 20:59:21 -04:00
behavioral_learning.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
config.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
decoding_utils.py updated readme and consistency 2026-04-20 20:59:21 -04:00
decoding_within_session.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
environment.yml updated readme and consistency 2026-04-20 20:59:21 -04:00
environment_from_history.yml updated readme and consistency 2026-04-20 20:59:21 -04:00
intrinsic_manifold_stability.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
joystick_task_decoding_rsa.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
manifold_eigenspectrum.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
manifold_methods.ipynb adding final analysis and plotting 2025-02-03 13:43:37 -05:00
mask_size_effect.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
navigation_mask_MNI_2mm.nii.gz adding navigation mask mni space 2025-08-26 16:51:48 -04:00
neural_EVR.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
neural_manifold_variance_analysis.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
order_effect.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
plotting_functions.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
README.md updated readme and consistency 2026-04-20 20:59:21 -04:00
realignment_consolidation.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
run_joystick_analyses.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
run_randomise.sh updated file paths 2026-04-20 21:29:21 -04:00
run_RT_session_decoding.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
searchlight_location_prediction_himalaya.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00
simulation_distributions.py adding final consistency checks and results files 2026-04-21 14:14:19 -04:00

avatarRT_analysis

updated April 2026, ELB, with supplemental analyses after revision & acceptance at Nature Neuroscience

This repository contains the analysis scripts for a real-time fMRI experiment testing neural manifold constraints on learning.


Environment

All scripts require the rtcloud_av1 conda environment. Change the final line of the provided file environment.yml to match your own conda installation and then build this environment using:

cd /path/to/avatarRT_analysis
conda env create -f environment.yml

then activate with

conda activate rtcloud_av1
# Interpreter: /Users/elb/miniconda3/envs/rtcloud_av1/bin/python

Run scripts from the avatarRT_analysis/ directory:

cd /path/to/avatarRT_analysis
python behavioral_results.py

Special package requirements

Package Purpose Notes
nibabel Load NIfTI mask files Standard conda install
TPHATE T-PHATE manifold embedding Pip install -- pip install tphate
MRAE Manifold regularized autoencoder Local package in MRAE/ subdirectory — install with pip install -e MRAE/
statsmodels OLS / ANOVA Standard conda install
himalaya Ridge regression (location decoding) pip install himalaya
ot (POT) Gromov-Wasserstein distances pip install POT

Configuring paths (config.py)

Edit config.py before running any scripts. The key path to set is:

DATA_PATH = os.path.expanduser('~/Desktop/BCI/avatarRT_dryad/avatarRT_subject_data')

This should point to the root of the subject data directory. Each subject's folder is expected to follow this structure:

<DATA_PATH>/
  avatarRT_sub_05/
    model/
      
    reference/
      mask.nii.gz             
    ses_0X/
      run_Y/            # run-level data (behavioral, functional)
        ...                   

The SESSION_TRACKER CSV (at <DATA_PATH>/session_tracker.csv) maps each subject to their IM/WMP/OMP session numbers and component indices.

Other paths (SCRATCH_PATH, INTERMEDIATE_RESULTS_PATH, FINAL_RESULTS_PATH) are set relative to the script directory and do not normally need to be changed.


Results directory structure

Scripts write output to results/ (created automatically):

results/
  results_public/       # xlsx files shared as source data with publication
  final_results/        # final per-subject summary CSVs 
  intermediate_results/ # intermediate cached computations
  plots/                # PDF figures output
  scratch/              # temporary cached embeddings / npys 

Statistical approach

All within-subjects comparisons use nonparametric paired randomization tests (10,000 iterations) via helper.permutation_test. Confidence intervals are computed with helper.bootstrap_ci (10,000 bootstrap samples). Between-subjects group comparisons (for real and simulated groups) use scipy.stats.ttest_ind(permutations=10000). OLS models and ANOVAs are implemented with statsmodels.


Scripts

Core analysis scripts

behavioral_results.py

BCI learning effects indexed by behavior (\Delta Brain Control).

Outputs — plots:

  • results/plots/behavioral_learning_sim.pdf — observed vs. simulated delta-BC per session type
  • results/plots/behavioral_learning_trialseries.pdf — trial-by-trial learning curves
  • results/plots/behavioral_learning_runwise.pdf — run-wise learning curves

Outputs — CSVs (results/results_public/):

  • behavioral_stats.csv — permutation test p-values and bootstrap CIs per condition

Requires: results/final_results/behavioral_change_session.csv, results/final_results/behavioral_change_trialseries_with_simulations.csv, results/final_results/behavioral_change_runwise_with_simulations.csv


neural_EVR_results.py

Neural alignment with manifold components (Explained Variance Ratio), across sessions and runs.

Outputs — plots:

  • results/plots/neural_EVR_*.pdf — EVR barplots per session type and run

Requires: pre-computed EVR CSVs in results/final_results/


joystick_results.py

Spatial decoding of avatar location during the joystick task, and RSA analysis.

decoding_within_session_results.py

Within-session decoding performance (run-wise cross-validation).

realignment_consolidation_results.py

Evidence for neural reconsolidation after learning.

Two analyses:

  1. EVR resampling — z-scores delta-EVR of the NFB feedback component vs. a null from all other components (10,000 draws).
  2. Cross-session decoding — IM-trained decoders evaluated across sessions; delta_mse (run 4 − run 1).

Outputs — plots:

  • results/plots/consolidation_zscored_evr.pdf
  • results/plots/consolidation_null_evr.pdf
  • results/plots/consolidation_delta_decoding.pdf

Outputs — CSVs:

  • results/results_public/random_resampling_components.csv
  • results/results_public/delta_decoding.csv

Requires (for computing, not loading): raw run data via analysis_helpers; optionally results/final_results/runwise_component_EVR_neural_analysis_run_change_control.csv


order_effects_results.py

Effect of counterbalancing order (WMP-first vs. OMP-first) on delta_BC and delta_EVR.

Outputs — plots:

  • results/plots/order_effects_barplot.pdf

Outputs — CSVs:

  • results/results_public/order_effects_lm_results.csv

Requires: results/final_results/behavioral_change_session.csv, results/results_public/main_results.csv


Supplemental / revision analyses

eigenspectrum_results.py

Control-space eigenspectrum: percent variance explained per manifold component per subject.

Outputs — plots:

  • results/plots/eigenspectrum_grid.pdf — per-subject component eigenspectrum
  • results/plots/eigenspectrum_by_condition.pdf — PEV by NFB condition
  • results/plots/eigenspectrum_correlations.pdf — PEV difference vs. learning outcomes

Outputs — CSVs:

  • results/results_public/manifold_eigenspectrum.csv

Requires: <DATA_PATH>/<subject>/model/bottleneck.npy for each subject; optionally results/results_public/main_results.csv for correlation plots.


mask_size_results.py

Per-subject neurofeedback mask size (voxel count) and its correlation with BCI/neural learning.

Outputs — plots:

  • results/plots/mask_size.pdf
  • results/plots/mask_size_learning.pdf

Outputs — CSVs:

  • results/results_public/mask_size_per_subject.csv
  • results/results_public/mask_size_correlations.csv

Requires: <DATA_PATH>/<subject>/reference/mask.nii.gz for each subject; results/results_public/main_results.csv


intrinsic_manifold_stability.py

Stability of the intrinsic neural manifold across days using Gromov-Wasserstein distances.

Outputs — plots:

  • results/plots/manifold_stability.pdf

Outputs — CSVs:

  • results/results_public/revision_gromov_wasserstein.csv
  • results/results_public/gromov_wasserstein_analysis_results.csv

Requires: ot (POT) and TPHATE packages; raw voxel data via analysis_helpers. T-PHATE embeddings are cached in results/scratch/joystick_analyses/ after first computation.


neural_manifold_variance_analysis.py

Additional variance analysis on the neural manifold.


searchlight_location_prediction_himalaya.py

Searchlight spatial decoding of avatar location (requires himalaya package).

Requires: run_randomise.sh for group-level FSL randomise statistics over searchlight maps.


Support modules

analysis_helpers.py

Shared statistical and data-loading utilities. Key functions:

  • permutation_test(data, n_iterations, alternative) — sign-flip paired permutation test; data shape (2, n_samples); returns (observed, pvalue, null_distribution)
  • bootstrap_ci(data, n_boot, ci, seed) — bootstrap CI of the mean; returns (mean, lower, upper)
  • load_component_data(...), run_EVR(...), load_all_joystick_data(...) — data loading helpers

plotting_functions.py

Shared plotting utilities. Key functions:

  • make_barplot_points(df, y, x, ...) — barplot with individual points, permutation tests, and significance annotations
  • make_barplot_errorbar(df, y, x, ...) — barplot with bootstrap error bars
  • determine_symbol(p) — converts p-value to significance symbol

config.py

Global configuration: paths, subject lists, session parameters, colors, plot style.


Excluded subjects

  • avatarRT_sub_12: dropped out of the study
  • avatarRT_sub_09: scanner issue (excluded from most analyses)
  • avatarRT_sub_20: fell asleep during scan (excluded from most analyses)

Subjects 09 and 20 are excluded via the SUBJECTS list at the top of each analysis script. Subject 12 is absent from SUB_NUMBERS in config.py.