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:

1. Apply HTFA to the dataset to discover a basis set of network “nodes”

2. Apply a dynamic correlation model to the HTFA fits to characterize the network dynamics

3. Visualize the network dynamics in two ways:

• An animated chord diagram

• An animated brain plot

Annotated bibliography

1. 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.

2. 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.

3. 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.

Table of contents:

• Overview

• Getting started

• Code

  • Initialization

  • Fit HTFA to data

  • Plotting HTFA global and local node locations

  • Compute dynamic correlations

  • Generate animated chord diagrams

  • Generate animated brain network plots

• Summary

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