| SOCR ≫ | TCIU Website ≫ | TCIU GitHub ≫ |
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.
require(TCIU)
require(DT)fmri_time_series: create four interactive time series graphs for the real, imaginary, magnitude, and phase parts for the fMRI spacetime data.
fmri_kimesurface: transform the fMRI time-series data at a fixed voxel location into a kimesurface.
fmri_image: create images for front view, side view, and top view of the fMRI image.
fmri_ts_forecast: forecast the fMRI data based on the time series
fmri_stimulus_detect: take a real/complex valued fMRI data and detects locations where stimulus occurs
fmri_post_hoc: conduct the post-hoc process (i.e. FDR correction and spatial clustering) for a 3-dimensional p-value array.
fmri_2dvisual: a visualization method, use ggplot2 to draw the brain from axial, sagittal and coronal view with activated area identified by p-values.
fmri_pval_comparison_2d: a plots arrangement method, which uses gridExtra to combine multiple 2d plots of the fMRI data together. This can bring convenience for users to compare the performance of different statistical tests based on the p-values they provide.
fmri_3dvisual: a visualization method, use plotly to draw the 3D plot of the brain with the activated areas determined by p-values.
fmri_pval_comparison_3d: a visualization method, use plotly to compare the activated parts inside in the brain using two sets of color palette. The activated parts are decided by p-values.
fmri_3dvisual_label: a visualization method to display 3d p-values region by region
fmri_ROI_phase1: calculate p-values on region of interest(ROI) of the brain
fmri_ROI_phase2: calculate tensor-on-tensor regression on region of interest(ROI) of the brain
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.
Details/Parameters
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:
dim_data : a vector of length 3 to identify the dimension of fMRI data user wants to simulate
mask : a 3D array of 1’s and 0’s or NULL. To specify the area inside the brain shell. One may use the mask data provided by this package, or generate a 3D array of 1’s and 0’s of the same dimension with the fMRI data to be generated. If NULL, then the function would generate a 3D sphere mask.
ons : a vector of the start time points of the time period when the fMRI data receives stimulation
dur : a vector of the time period when the fMRI data receives stimulation.
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
dim(fmri_generate$fmri_data)## [1] 64 64 40 160Details/Parameters
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:
fmridata : a 4D array which contains the spatial and temporal record of fMRI result or a single complex valued vector
voxel_location : a 3D array indicating the spatial location of the brain. If is.4d is false, set the voxel_location as NULL.
is.4d : The default is TRUE. If change to false, input a vector instead of a 4D array.
ref : The default is NULL. User can input an outside extra reference object to include in the final result.
Example
fmri_time_series(sample_save[[9]], voxel_location = NULL, is.4d = FALSE, ref = sample_save[[8]])Details/Parameters
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:
fmridata : a 4D array which contains the spatial and temporal record of fMRI result or a single real valued vector.
voxel_location : a 3D array indicating the spatial location of the brain.
is.4d : The default is true. If change to false, need to input a vector instead of array.
Example
# 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 on / 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]]Details/Parameters
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:
fmridata : a 4D array contains information for the fMRI spacetime image. The data should only contain the magnitude for the fMRI image.
option : The default is ‘manually’. If choose ‘auto’, then this function will lead you to key in the space (x,y,z) parameters and time (time) parameter for this function to generate graphs.
voxel_location : a 3D array indicating the spatial location of the brain. If option is auto, set the voxel_location as NULL.
time : time location for the voxel
Example
fmri_image(fmri_generate$fmri_data, option="manually", voxel_location = c(40,22,33), time=4)