This repository is for the computation of functional connectivities (covariance matrices) for patients in the HCP_1200 dataset. There are 1113 patients in the HCP_1200 dataset. A subset of them have at least one (of two possible) fmri scans for the REST1 portion of the dataset. Each available scan is parcelized according to an atlas (Deskian or Destreuix), activity values are averaged in these parcellizations for each time point thus creating a vector observation (each entry corresponds to a brain regions). These observations are then used to compute some functional connectivity matrix, either using all observations or windowed/sampled subsets.

If you would like to download these raw fmri/atlas files for yourself, see my other repo hcp-download-script here:
    https://github.com/maxwass/hcp-download-script

If you would like to read more about this data and how it was collected, see the review paper:
    https://pubmed.ncbi.nlm.nih.gov/22366334/

Assumed directory structure:
    -It is assumed that all required fMRI/atlas files are in a directory named 'brain_data', and each patient has its own directory with the subject id as the directory name.
    -If directory path is changed, update the way the path2fmri variable is constructed appropriately in files _______
 
## Things to change for different machines **
1) utils/path_to_project()
    specify local path to project directory
2)



Project Layout:


construct_datasets/
    subsampled_ds.m
        Create subsampled, windowed,, and/or frequency filtered dataset of SCs/FCs.
    test_dataset_creation.m
        Ensure data placed into dataset tensors properly by reloading the raw .mat file and comparing
    

viz_tools/
    viz_scs/
        inspect_scs.m
            Sanity checking provided SCs for NaNs, all zeros, etc.
        diffusion_on_scs.m
            Showing representative FCs using different diffusion polynomials over providede SCs.
        explore_brain_data.m
            Plot graphs with increasing threshold for edges (and thus more sparsity).

    viz_fcs/
        fMRI_signals_explore.m
            Plot energy distribution of signals for LR and RL signals. Plot characterstics of mean vectors in time and freq.
        fc_trajectories_gui/  ===> visualize how fcs changes at small windows along time series
            fc_trajectories.mlapp
                GUI app to explore time series and fc tracjectories with filters.
            plot_grid.m
                Handles plotting for app.

    energy_distrib/
        energy_vs_binned_variation.m
            Plot energy in each variation range for all scans over many GSOs and variation metrics.


data_loading/
    fc_loading/
        ScanInfo.m
            Class abstracting away a fmri scan. Has properties to load fmri data and corresponding SC.
        load_functional_dtseries.m
            Takes raw fmri & atlas file, averages activity in atlas brain regions.
            Returns N x num_observations matrix - each column is a vector observation
        load_raw_fmri.m
            Calls cifti function for reading raw fmri files.
        load_atlas.m
            Calls cifit function for reading atlas parcellizations specified by 'atlas'.
        cifti_matlab/
            Repositiory of functions for reading brain imaging files.
    sc_loading/
        extract_scs.m
            Given patient id, load corresponding SC.
            
construct_fcs/
    windowed_signals.m
        Given matrix of vector observations (the columns) construct subsets (windows) of signals by sliding window frame over matrix.
    random_subsets.m
        Returns equally sized subsets (slices of a tensor) of matrix of observations via sampling.
    preprocess_fcs.m
        Given tensor of fcs, apply filter to each fc slice to determine which should be removed.
    

data_accounting/
    data_accounting.m
        Analysis on what data we have for each patients, and which scans are needed
 
    compare_datasets.m
        Viz compares old dataset given by Zhengwu to new computed dataset.
        Plotting to compare old correlation fcs to new computed correlation fcs
        Outputs jpgs showing comparison for each patient
   
    subject_list_dir_debug.m
        Found repeated subject in subject_list outputed by function in hcp-batch-download repo

           

data/  ==> .mat files outputted and/or used by other scripts
    cached_desikan/
        create_cached_data.m
            Load and process fmri files with given atlas (desikan) and cache result for faster loading later.
        fix_cached_data_format.m
            For changing contents/variables of all cached files.
        rfMRI_REST1/ ==> cached data files for task REST1

    hcp_1200_subject_list.mat
        List of all subject on HCP_1200 aws s3 server.
        Includes all patients, regardless of what scans they have.

    subject_missing_fc_data.mat
        Set of patient ids
            missing_LR = all patients in hcp_1200  w/o an LR scan for REST1
            missing_RL = all patients in hcp_1200 w/o an RL scan for REST1
            missing_LR_and_RL = patients in hcp_1200 missing LR & RL for REST1 (interesect of prev sets)
            type = string indicating which fmri data is being referenced

    correlations_desikan_old.mat
        1058 87x87 Correlation (not Covariance) matrices provided by Zhengwu to Yang, and from Yang to me.
        Unclear if these are if lr, rl, mean.
        Desikan atlas, subcortical nodes come LAST (69:87), corresponding patient ids in subject_list_sc
        Missing data for patients relative to scs_desikan.mat. Aka patients with scs but no fcs (here)
            patient ids of missing data <-> [150019, 160931, 173233, 179548, 351938, 693461, 995174]

    scs_desikan.mat
        1065 87x87 structural connectivities provided by Zhengwu.
        Desikan atlas, Subcortical nodes come FIRST (1-19), corresponding patient ids in subject_list_sc



===================Attributions========================
    Zhengwu Zhang - professor at UNC
    Martin Cole   - phd student at UofR
    FieldTrip     - use of cifti file reading libary - http://www.fieldtriptoolbox.org
    HCP           - human connectome project - http://www.humanconnectome.org


If you make use of this repository, please cite:
-Wasserman, Mateos ....PAPER TO BE POSTED

If you make use of the DATA in this repository, please ALSO cite:
-Zhang, Zhengwu, Maxime Descoteaux, Jingwen Zhang, Gabriel Girard, Maxime Chamberland, David Dunson, Anuj Srivastava, and Hongtu Zhu. "Mapping population-based structural connectomes." NeuroImage 172 (2018): 130-145.

-Zhang, Zhengwu, Genevera I. Allen, Hongtu Zhu, and David Dunson. "Tensor network factorizations: Relationships between brain structural connectomes and traits." Neuroimage 197 (2019): 330-343.


Acknowledgements/citations as requirement for use of HCP Data:
-"Data were provided [in part] by the Human Connectome Project, WU-Minn Consortium (Principal Investigators: David Van Essen and Kamil Ugurbil; 1U54MH091657) funded by the 16 NIH Institutes and Centers that support the NIH Blueprint for Neuroscience Research; and by the McDonnell Center for Systems Neuroscience at Washington University."

-Matthew F. Glasser, Stamatios N. Sotiropoulos, J. Anthony Wilson, Timothy S. Coalson, Bruce Fischl, Jesper L. Andersson, Junqian Xu, Saad Jbabdi, Matthew Webster, Jonathan R. Polimeni, David C. Van Essen, and Mark Jenkinson (2013).
The minimal preprocessing pipelines for the Human Connectome Project. Neuroimage 80: 105-124.

-Jenkinson M, Beckmann CF, Behrens TE, Woolrich MW, and Smith SM. (2012). FSL. NeuroImage, 62:782-790. 

-Fischl B. (2012). FreeSurfer. NeuroImage, 62:774-781.

-Jenkinson M, Bannister PR, Brady JM, and Smith SM. (2002). Improved optimisation for the robust and accurate linear registration and motion correction of brain images. NeuroImage 17(2):825-841.

-Glasser MF, and Van Essen DC. (2011). Mapping human cortical areas in vivo based on myelin content as revealed by T1- and T2-weighted MRI. J Neurosci. 31:11597-11616


Links to HCP compliance rules
    https://www.humanconnectome.org/study/hcp-young-adult/document/wu-minn-hcp-consortium-open-access-data-use-terms
    https://www.humanconnectome.org/study/hcp-young-adult/document/hcp-citations