Functions & Workflow of TCIU Analytics"


This document is set up for package TCIU which is developed in the R environment.

In this vignette, we introduce the detailed usage of all the functions with examples in the TCIU R package. Besides, we focus in the use of fmri_stimulus_detect() function on our simulated brain fMRI data (generated by fmri_simulate_func()) to get the p-value to locate the stimulated parts in the brain as well as the post-hoc process and result visualization. User can also refer to the concise steps in our website TCIU Predictive Analytics.


Function list

FMRI data simulation

Visualization of the fMRI data in time-series

Activated areas detection

Activated areas visualization

Activated areas detection by three-phase analysis

Analysis of simulated fMRI data

Here we simulate our 4D fMRI data with its first three dimension as 64 times 64 times 40 and its fourth dimension as the 160-time length. We specify the dimension of the data, starting time points when the fMRI data receives the stimulus and the duration of each stimulated time periods to get it. As we want our data shaped like a brain, we provide a brain-shaped mask for it. Otherwise, it will generate a sphere mask automatically.


The function fmri_simulate_func() is used to simulate fMRI data with specified dimension and total time points. The fMRI data can be brain-shaped by using the mask data provided in our package, if the dimension fits the same as our data (c(64, 64. 40)). Otherwise, the function will generate a 3D sphere data with multiple activated part inside. The activated parts can be detected based on the p values.

Parameters in this function:

fmri_generate = fmri_simulate_func(dim_data = c(64, 64, 40), mask = mask, 
                                   ons = c(1, 21, 41, 61, 81, 101, 121, 141), 
                                   dur = c(10, 10, 10, 10, 10, 10, 10, 10))

# the outputs include simulated fMRI data, its mask, 
# the starting time points of the stimulated period and its duration 
# as well as all the stimulated time points

Visualization of the fMRI data in time-series

Function "fmri_time_series"


We first provide an interactive time-series visualization for a fixed voxel. Since the input fMRI data needs to be complex-valued, we provide a sample complex voxel's time-series vector and a sample reference plotly object.

The function fmri_time_series() is used to create four interactive time series graphs for the real, imaginary, magnitude, and phase parts for the fMRI spacetime data.

Parameters in this function:


fmri_time_series(sample[[5]], voxel_location = NULL, is.4d = FALSE, ref = sample[[4]])

Function "fmri_kimesurface"


We second provide a function to transform the fMRI time-series at a fixed voxel location into a kimesurface (kime-series).

The function fmri_kimesurface() is used to display in 3D the kime-series as 2D manifolds (kimesurface) over the Cartesian domain. User can choose to provide the 4D array of the fMRI spacetime image and the voxel_location or a single TS vector.

Parameters in this function:


# a data-frame with 160 rows and 4 columns: time (1:10), phases (8), states (2), and fMRI data (Complex or Real intensity)
datatable(fmri_kimesurface(fmri_generate$fmri_data, c(44,30,33))[[1]])
# ON Kime-Surface
fmri_kimesurface(fmri_generate$fmri_data, c(44,30,33))[[2]]
# User can try themself to plot the off / on&off figure
# OFF Kime-Surface 
# fmri_kimesurface(fmri_generate$fmri_data, c(44,30,33))[[3]]
# ON&OFF Kime-Surface 
# fmri_kimesurface(fmri_generate$fmri_data, c(44,30,33))[[4]]

Function "fmri_image"


The function fmri_image() is used to create images for front view, side view, and top view of the fMRI image. When providing the 4D array of the fMRI spacetime image and input the x,y,z position of the voxel, three views of the fMRI image and the time series image of the voxel will be shown.

Parameters in this function:


fmri_image(fmri_generate$fmri_data, option="manually", voxel_location = c(40,22,33), time=4)

Function "fmri_ts_forecast"


The function fmri_ts_forecast() is used to forecast the fMRI data based on the time series.

Parameters in this function:


smoothmod<-GaussSmoothArray(fmri_generate$fmri_data, sigma = diag(3,3))
fmri_ts_forecast(smoothmod, voxel_location=c(41,44,33))

Activated areas detection

Load and display the data

Here we apply fmri_stimulus_detect() function on our simulated fMRI data to get the 3D array p value data. We use t-test here for simplicity. But we also have Wilcoxon test, HotellingT2 test, gLRT test for complex data, generalized likelihood test, generalized linear model and on-off intensity difference method to generate the p value to detect the stimulated parts in the fMRI data. The smaller the p value is, the higher level the stimulated part is.

p_simulate_t_test = 
fmri_stimulus_detect(fmridata= fmri_generate$fmri_data, 
                     mask = fmri_generate$mask,
                     stimulus_idx = fmri_generate$on_time,
                     method = "t-test" , 
                     ons = fmri_generate$ons, 
                     dur = fmri_generate$dur)


From the dimension of the generated p_simulate_t_test, we know it is a 3D array p value with its dimension as 64 times 64 times 40.

Analysis of real fMRI data

As we save a 3D array p value data generated from the real fMRI brain data, here we can apply post-hoc test on it to improve the performance. We can apply FDR correction and spatial clustering to our 3D array p value data to prevent the high proportion of false positive voxels and keep only spatially connected significant voxels. Notice that when doing spatial clustering, the threshold(spatial_cluster.thr) and cluster size(spatial_cluster.size) are needed to filter contiguous clusters of locations in a 3D array that are below some threshold and with some minimum size.

# do the FDR correction
pval_fdr = fmri_post_hoc(phase2_pval , fdr_corr = "fdr",
                         spatial_cluster.thr = NULL,
                         spatial_cluster.size = NULL, 
                         show_comparison = FALSE)

# do the spatial clustering
pval_posthoc = fmri_post_hoc(pval_fdr, fdr_corr = NULL,
                             spatial_cluster.thr = 0.05,
                             spatial_cluster.size = 5, 
                             show_comparison = FALSE)

Visualization and Comparison of fMRI data

2D and 3D visualization

We generate the 2D plot and 3D interactive of our simulated fMRI data based on the p value generated above from sagittal, coronal and axial view.

# the output figure is hidden
for(axis in c("x", "y", "z")){
  axis_i = switch(axis, 
                  "x" = {35},
                  "y" = {30},
                  "z" = {22})
  print(fmri_2dvisual(p_simulate_t_test, list(axis, axis_i), 
                      hemody_data=NULL, mask=fmri_generate$mask, 
                      p_threshold = 0.05, legend_show = TRUE, 
                      method = "scale_p",
                      color_pal = "YlOrRd", multi_pranges=TRUE))
fmri_3dvisual(p_simulate_t_test, fmri_generate$mask, 
                            p_threshold = 0.05, method="scale_p",

Comparison of performance of different methods on the same fMRI data

We can use fmri_pval_comparison_3d() to visualize two p value data to see how they perform differently on detecting stimulated parts by 3D plot. Here we compare the difference of stimulated parts of two different fMRI data with the same mask, since our original fMRI is too big to use here for different statistical test. The output figure is similar to 3D visualization, so we hide them here.

# the two p value are the p value generated based on the simulated fMRI
# and the p value saved in the package and finished post hoc test
# the output figure is hidden
fmri_pval_comparison_3d(list(p_simulate_t_test, phase3_pval), mask, 
                                list(0.05, 0.05), list("scale_p", "scale_p"), 

We can also use fmri_pval_comparison_2d() to visualize whatever number of p value (generated by different statistical tests on the same fMRI data) to see their difference by 2D plot. For simplicity here we only compare two different 3D array p value data.

fmri_pval_comparison_2d(list(p_simulate_t_test, phase3_pval), 
                        list('pval_simulated', 'pval_posthoc'),
                        list(list(35, 33, 22), list(40, 26, 33)), 
                        hemody_data = NULL, 
                        mask = mask, p_threshold = 0.05, 
                        legend_show = FALSE, method = 'scale_p',
                        color_pal = "YlOrRd", multi_pranges=FALSE)

Activated areas detection by three-phase ROI Analysis

Phase1: Detect Potential Activated ROI


The function fmri_ROI_phase1 is used to calculate p-values of ROIs for a given real-valued fMRI data, which is usually the 1st phase of a ROI 3-phase analysis.


ROI_phase1 = fmri_ROI_phase1(fmri_generate$fmri_data, mask_label, mask_dict, stimulus_idx = fmri_generate$on_time)

Phase2: ROI-Based Tensor-on-Tensor Regression


The function fmri_ROI_tensor_regress is used to detect locations where stimulus occurs by calculating the p-values of the ROI-based tensor-on-tensor regression. Two methods, namely 't_test' and 'corrected_t_test',can be chosen to calculate the p-values from the regression coefficients.


ROI_phase2 = fmri_ROI_phase2(fmridata = fmri_generate$fmridata, label_mask = mask_label, 
                             ROI_label_dict = mask_dict, stimulus_idx = fmri_generate$on_time,
                             stimulus_dur = fmri_generate$dur, rrr_rank = 3,
                             fmri.design_order = 2, fmri.stimulus_TR = 3, 
                             method = "t_test", parallel_computing = TRUE, max(detectCores()-2,1))

Phase3: FDR Correction and Spatial Clustering


# do the FDR correction
# do the spatial clustering
ROI_phase3 = fmri_post_hoc(ROI_phase2 , fdr_corr = "fdr",
                           spatial_cluster.thr = 0.05,
                           spatial_cluster.size = 5, 
                           show_comparison = FALSE)

3D visualization based on the activated areas by regions


The function fmri_3dvisual_region is used to visualize the 3D plot of the brain with activated parts region by region. The parameters are very similar to fmri_3dvisual with some additional parameters to assign the region information.


# the output figure is hidden due to the size of vignettes
label_index = mask_dict$index
label_name = as.character(mask_dict$name)
label_mask = mask_label
fmri_3dvisual_region(phase1_pval, mask_label, label_index, label_name, title = "phase1 p-values")
# the output figure is hidden due to the size of vignettes
fmri_3dvisual_region(list(phase2_pval,phase3_pval), mask_label,
                     label_index, label_name, title = "phase2&3 p-values")

Try the TCIU package in your browser

Any scripts or data that you put into this service are public.

TCIU documentation built on April 30, 2021, 5:08 p.m.