Hierarchical Topographic Factor Analysis
By Jeremy R. Manning (jeremy.r.manning@dartmouth.edu) and Paxton C. Fitzpatrick (Paxton.C.Fitzpatrick@dartmouth.edu)
Overview
In this demonstration, we’ll be using the BrainIAK Python toolbox to apply Hierarchical Topographic Factor Analysis (HTFA) to an fMRI dataset.
The demo will comprise three main steps:
Apply HTFA to the dataset to discover a basis set of network “nodes”
Apply a dynamic correlation model to the HTFA fits to characterize the network dynamics
Visualize the network dynamics in two ways:
An animated chord diagram
An animated brain plot
Annotated bibliography
Manning JR, Ranganath R, Norman KA, Blei DM (2014). Topographic Factor Analysis: a Bayesian model for inferring brain networks from neural data. PLoS One, 9(5): e94914. link Describes a single-subject model (TFA) for inferring brain network hubs and applies it to a semantic decoding dataset.
Manning JR, Zhu X, Willke TL, Ranganath R, Stachenfeld K, Hasson U, Blei DM, Norman KA (2018). A probabilistic approach to discovering dynamic full-brain functional connectivity patterns. NeuroImage, 180: 243-252. link Describes a multi-subject (hierarchical) model (HTFA) for inferring shared brain network hubs and applies it to a story listening and movie viewing dataset.
Owen LLW, Chang TH, Manning JR (2020). High-level cognition during story listening is reflected in high-order dynamic correlations in neural activity patterns. bioRxiv. link Describes a model for inferring network dynamics from timeseries data and applies it to HTFA fits to a story listening dataset.
Getting started
The easiest way to run this notebook is to download and install Docker on your local machine, and then build the Docker image in this folder. That will install the necessary toolboxes and dependencies, and will also download the data you’ll be analyzing. Follow the instructions for your platform to download and install Docker, and then start the Docker Desktop application.
After you’ve installed Docker, to build the docker image, just navigate to this folder and run:
docker build --rm --force-rm -t htfa .
To start the image for the first time, run:
docker run -it -p 8888:8888 --name htfa -v $PWD:/mnt htfa
and on subsequent times, run:
docker start htfa && docker attach htfa
When the docker image is started, it will automatically start a Jupyter notebook server. Copy and paste the third link into a browser to interact with this notebook.
To stop running the container, run:
docker stop htfa
Code
Run the cells below (in sequence) to load in the example dataset, fit HTFA to the data, and visualize the resulting network dynamics.
Initialization
Import libraries and helper functions and load the dataset. The dataset we’ll be analyzing is a subset of the story listening dataset collected by Simony et al. (2016).
# the next two lines suppress a (meaningless) warning about the graphics backend
import warnings
warnings.simplefilter('ignore')
# data science and visualization libraries
import numpy as np
import pandas as pd
import nibabel as nb
import nilearn as nl
import timecorr as tc
import seaborn as sns
from IPython.display import HTML
# system libraries
from mpi4py import MPI
import os, sys
from glob import glob as lsdir
import pickle as pkl
# brainiak
from brainiak.factoranalysis.htfa import HTFA
# convenience functions from helpers.py
from helpers import nii2cmu, cmu2nii, animate_chord, animate_connectome, opts, opts2str, htfa2dict, dict2htfa, local_params, global_params, plot_nodes