Beauchamp:TensorECOG

Regularized Higher-Order Partial Least Squares Analysis for ECoG Data

By Frederick Campbell and Kelly Geyer, June 2017

kelly.l.geyer@rice.edu

Introduction

This page contains documentation of our MATLAB package for the tensor factorization algorithm Regularized Higher-Order Partial Least Squares (RHOPLS) and Principal Component Analysis (RHOPCA). These algorithms are specifically designed for electrocorticography (ECoG) data, with dimensions consisting of trials, electrodes, epoch time, and frequency.

Current capabilities:

1. Data pre-processing: multiple methods for scaling data and removing outlier trails
2. Regularized Higher-Order PCA: Implementation of RHOPCA for ECoG data
3. Regularized Higher-Order PLS: Implementation of RHOPLS for ECoG data
4. Parameter tuning for RHOPLS: Tuning function to select best parameters for RHOPLS

Upcoming capabilities:

1. R wrapper functions: Ability to use this package in R
2. Integration with RAFE: Ability to visualize RHOPCA heatmaps with RAFE tool, as well as SUMA
3. Parameter tuning for RHOPCA: Tuning function to select best parameters for RHOPCA

Requirements

Required Software:

1. R
2. MATLAB

Obtaining Code

This package is available on the GitLab page https://gitlab.com/klgeyer/rhop. This is currently a private page so contact Kelly Geyer to obtain an invitation to page or current copy of code.

Configuration

Configuration for Mac OSX

1. Create terminal command 'matlab' by typing the following lines in the terminal. For example <path to matlab bin> could be "/Applications/MATLAB_R2015a.app/bin"

   $ export PATH=$PATH:<path to matlab bin>
   $ source ~/.bash_profile

Test this by typing the following, which should return "<path to matlab bin>/matlab"

   $ which matlab

2. Configure variables for rhopls code by editing the config.yaml file as needed. You can check values with the commands below

   $ which R
   $ which Rscript

3. Make R to recognize the command matlab. Run the following terminal commands

   $ touch ~/.Renviron
   $ echo "export PATH=\"/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:$PATH\"" >> ~/.Renviron
   $ touch ~/.Renviron.site
   $ echo "export PATH=\"/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:$PATH\"" >> ~/.Renviron.site

Test this step by running the following command in R

   > system("matlab -nodesktop")

Install Package

Install the MATLAB package with the following commands, which are use to include at the beginning of any .m script that uses this package

   % Install RHOPLS package
   cd(rhopls_dir);
   addpath(pwd);
   savepath;
   % Install required toolboxes
   rhopls_setup();

Processing ECoG Data for Analysis

The RHOPLS package provides several methods of processing ECoG data before an analysis. These include several methods of standardization, as well as removal of outlier trials. The function process_patient_data implements these in a user-friendly wrapper. Ultimately it creates the design tensor for a single patient, which is a 4-dimensional tensor with dimensions (trials x electrode x frequency x time). .

Data Standardization Methods:

1. none: When using the <load_patient_data> function this avoids implementing any standardization. However, it is not an option for the standardize_data function
2. flatten_trials: This function flattens the ECoG tensor by trial, or first dimension, and then centers and scales data according by user options
3. array_normal: This function centers and scales data using the array normal method, according by user options. The array normal distribution is a higher-order generalization of the multivariate normal distribution. We estimate a mean and covariance assuming the tensor was generated via the array normal distribution and use the estimated parameters to center and scale the tensor.

Example

In following example, we mean center and scale the flattened tensor to standardize it. Additionally, outlier are removed. Users can also choose to set either center and scale to false.

   %% Load and process ECoG data
   % Import and create a design tensor for patient k
   std_method = 'flatten_trials';
   center = true;
   scaled = true;
   rm_outliers = true;
   [X, outliers] = process_patient_data(patient_dir, ... 
                       'standardizationMethod', std_method, ... 
                       'center', center, ...
                       'scaled', scaled, ...
                       'removeOutliers', rm_outliers);

ECoG Regularized Higher-Order Least Squares Regression

parameter tuning, fit model

ECoG Regularized Higher-Order Principal Component Analysis

parameter tuning, fit model

Results

do analysis here, show plots

References

1. Frederick Campbell, "Interpretable Brain Decoding for Electrocorticography Data though Regularized High Order Partial Least Squares." Publication in progress.
2. Brett W. Bader, Tamara G. Kolda and others. MATLAB Tensor Toolbox Version 2.6, Available online, February 2015. URL: http://www.sandia.gov/~tgkolda/TensorToolbox/.