# Experiment 2 (HCP)
Contains scripts for connectopic and retinotopic analyses of the HCP dataset in
Experiment 2.
We outline the contents of the repository below, in the (approximate) order
they need to be run.
> Many of the scripts make reference to a `basedir` variable - this should be
> set to the top-level directory containing all of the subject directories.
## preproc
Scripts used for setting up directory structure, and running initial
pre-processing stages.
* `unpack_data.sh` - Copies/symlinks data downloaded from the HCP into a nicer
directory structure. This sets up the basic structure of subject directories
that further scripts rely on.
* `anat2freesurfer.sh` - Converts HCP surface files from GIFTI to Freesurfer
format for improved compatibility with Freesurfer.
* `curv2freesurfer.py` - Converts HCP curvature files from CIFTI to Freesurfer
format for improved compatibility with Freesurfer.
* `preproc_data.py` - Applies additional pre-processing to functional data.
Specifically, converts timeseries to percent signal change, and applies
spatial smoothing (surface and volume based).
## retinotopy
Scripts are used for performing pRF analyses of retinotopy data and defining V1
labels.
* `extract_occipital_label.sh` - Extracts occipital lobe label from Freesurfer
atlas and transforms to HCP surface. This is used to provide an approximate
label that can be used to restrict pRF fits to the occipital lobe to save on
computation time.
* `fit_pRF.m` - Performs pRF fits. Adapted from code provided by Benson et al.
(2018), Journal of Vision; https://osf.io/bw9ec/ . Code has additional
external dependencies which we do not redistribute here - see docstring in
script for details on how to obtain these.
* `convert_pRF_to_freesurfer.sh` - Converts outputs from *fit_pRF.m* script
from CIFTI to MGZ format for compatibility with Freesurfer.
* `display_in_freeview.sh` - Display phase maps in freeview for manual drawing
of V1 ROIs. These ROIs were saved out as Freesurfer label files.
* `convert_labels_to_cifti.sh` - Once V1 labels have been defined, this script
converts them from Freesurfer back to CIFTI format.
* `restrict_maps_to_V1.py` - Once V1 labels have been defined, this script
restricts the pRF eccentricity and polar maps to those labels. Saves in
CIFTI, MGZ, and numpy formats. Mostly useful for providing retinotopic inputs
to connectopic mapping scripts.
## connectopy
Scripts for calculating connectivity fingerprints and performing connectopic
mapping.
* `calc_connectivity_fingerprints.py` - Calculates the functional connectivity
fingerprints within V1 by correlating the pre-processed timeseries. Provides
options for measuring connectivity between V1 and all other cortical and
subcortical grayordinates, just cortical grayordinates, just grayordinates
structures, cortical and subcortical grayordinates substituted with noise, or
purely within V1.
* Various scripts perform connectopic mapping, each offering different
algorithms:
* `do_diffusion_map.py` - Diffusion maps
* `do_isomap.py` - Isomap
* `do_kernel_pca.py` - Kernal PCA, using polynomial and RBF kernels
* `do_linear_embedding.py` - PCA and ICA
* `do_LLE.py` - (M)LLE and LTSA
* `do_spectral_embedding.py` - Spectral Embedding
* `do_tSNE.py` - t-SNE
## stats
Runs statistical analyses on the prediction accuracies (absolute correlations
between retinotopic and connectopic maps).
* First, various scripts are used to extract the prediction accuracies
(correlations) from each connectopic mapping algorithm and compile the values
over subjects. The outputs are used as inputs to further statistical
analyses.
* `extract_corrs-spectral_embedding.py` - Extracts correlations from spectral
embedding algorithm. Dedicated script is needed to handle the different
graph types (weighted/unweighted $\times$ full/radius/kNN).
* `extract_corrs-kernel_pca.py` - Extracts correlations from kernel PCA
algorithm. Dedicated script is needed to handle the different kernel types
(polynomial and RBF).
* `extract_corrs-other_embeddings.py` - Extracts correlations for all other
connectopic mapping technqiues (PCA, ICA, MLLE, LTSA, Isomap, diffusion
maps, and t-SNE).
* `analyse_corrs-spectral_embedding.R` - Performs analysis of correlations
within spectral embedding algorithm. Dedicated script is needed to handle the
different graph types. Runs a three-way repeated-measures ANOVA with factors
for the map type (eccentricity, polar angle), graph type, and task (rest,
movie-watching). Also performs one-sample t-tests to test correlations in
each case against zero.
* `analyse_corrs-other_embeddings.R` - Performs analysis of correlations for
all other algorithms (PCA, ICA, kernel PCA (polynomial and RBF), LLE, LTSA,
Isomap, diffusion maps, and t-SNE). Runs a two-way repeated-measures ANOVA
with factors for the map type (eccentricity, polar angle) and task (rest,
movie-watching). Also performs one-sample t-tests to test correlations in
each case against zero.
* `compare_corrs_between_embeddings.R` - Compares correlations across
connectopic mapping algorithms via a three-way repeated-measures ANOVA with
factors for the map type (eccentricity, polar angle), algorithm type, and
task (rest, movie-watching).
* `compare_corrs_between_sources.R` - For spectral embedding, Isomap, and
diffusion map algorithms, compares correlations for connectopic maps based on
different connectivity sources (cortex+subcortex, cortex-only,
subcortex-only, within-V1, and cortex+subcortex substituted with noise). Runs
a four-way repeated-measures ANOVA with factors for the algorithm type, map
type (eccentricity, polar angle), connectivity source, and task (rest,
movie-watching).
* `cross_corr_embedding.py` - Calculates correlations between connectopic maps
produced by each connectopic mapping algorithm.
## python_utils
Assorted utility functions and classes for use by other python scripts
* `cifti.py` - Tools for handling data from CIFTI files.
* `manifold.py` - Contains assorted functions and classes used for manifold
learning.
* `stats.py` - Tools used by statistics Python scripts.
## R_utils
Contains `R_utils.R`, containing tools used by statistics R scripts.