README.md

rtapas

Build
Status AppVeyor Build
Status CRAN_Status_Badge Coverage
Status

The goal of rtapas is to determine a subject-specific threshold to apply to multiple sclerosis lesion probability maps for automatic segmentation. This R package is based on the Thresholding Approach for Probability Map Automatic Segmentation (TAPAS) method. The methods are in progress for publication. This package creates data structures necessary for training the TAPAS model. After training, the model can be used to predict subject-specific thresholds to use on probability maps for automatic lesion segmentation. Methods can be extended outside of multiple sclerosis lesion segmentation but have not been validated.

Installation

To get the latest development version from GitHub:

# install.packages('remotes')
library(remotes)
remotes::install_github('avalcarcel9/rtapas')

We are currently working to get the package on Neuroconductor.

Function Documentation

The TAPAS package contains a number of functions to generate data required for training, train the TAPAS model, and predict subject-specific thresholds based on the trained TAPAS model. The functions, defaults, and usage are provided below.

tapas_data

tapas_data(thresholds = seq(from = 0, to = 1, by = 0.01),
           pmap,
           gold_standard,
           mask,
           k = 8,
           subject_id = NULL,
           verbose = TRUE)

Description:

This function creates the training vectors for a single subject from a probability map, a gold standard mask (normally a manual segmentation), and a brain mask. For a grid of thresholds provided and applied to the probability map the function calculates Sørensen’s–Dice coefficient (DSC) between the automatic image and the gold standard image. The function also calculates the volume associated with thresholding at each respective threshold.

Usage:

Return:

A tibble containing the training data for a single subject. The data contains columns threshold, Sørensen’s–Dice coefficient (dsc), and volume.

tapas_data_par

tapas_data_par(cores = 1,
               thresholds = seq(from = 0, to = 1, by = 0.01),
               pmap,
               gold_standard,
               mask,
               k = 8,
               subject_id = NULL,
               ret = FALSE,
               outfile = NULL,
               verbose = TRUE)

Description:

This function wraps tapas_data to run in parallel. This function creates the training vectors for all subjects from a probability map, a gold standard mask (normally a manual segmentation), and a brain mask. For a grid of thresholds provided and applied to the probability map the function calculates Sørensen’s–Dice coefficient (DSC) between the automatic image and the gold standard image. The function also calculates the volume associated with thresholding at each respective threshold.

Usage:

Return:

A list with the subject-level tibble object in each element returned from tapas_data for each subject. ret must be TRUE to return objects locally. To save objects a vector of outfile file paths must be provided.

tapas_train

tapas_train(data, 
            dsc_cutoff = 0.03, 
            verbose = TRUE)

Description:

This function trains the TAPAS model using all binded subject-level tibbles produced from the tapas_data function. The TAPAS model is fit and clamp data is calculated. The clamp data contains the predicted threshold when using the 10th and 90th percentile volume from training data.

Usage:

Return:

A list with the TAPAS model (tapas_model) of class gam and the a tibble with the clamp information (clamp_data). The clamp information contains the TAPAS-predicted smallest and largest threshold to be applied by using estimates related to the volume at the 10th and 90th percentile.

tapas_predict

tapas_predict(pmap, 
              model, 
              clamp = TRUE, 
              k = 8, 
              verbose = TRUE){

Description:

This function takes a probability map for a single subject and predicts the subject-specific threshold to apply based on the TAPAS model generated from tapas_train. The function will return a list of objects including the TAPAS predicted subject-specific threshold, the lesion mask produced from applying this threshold, and the lesion mask produced from using the group threshold.

Usage:

Return:

A list containing the TAPAS predicted subject-specific threshold (subject_threshold), the lesion segmentation mask obtained using the TAPAS predicted subject-specific threshold (tapas_binary_mask), and the lesion segmentation mask obtained using the group threshold (group_binary_mask).

tapas_predict_par

tapas_predict_par(cores = 1,
                  pmap,
                  subject_id,
                  model,
                  clamp = TRUE,
                  k = 8,
                  ret = FALSE,
                  outfile = NULL,
                  verbose = TRUE)

Description:

This function wraps tapas_predict to run in parallel. This function takes probability maps across subjects and predicts the subject-specific threshold to apply based on the TAPAS model generated from tapas_train. The function will return or save a list of objects for each subject including the TAPAS predicted subject-specific threshold, the lesion mask produced from applying this threshold, as well as the lesion mask produced from using the group threshold.

Usage:

Return:

A nested list. Each element in the list contains subject-level data returned from tapas_predict.



neuroconductor/rtapas documentation built on Oct. 13, 2019, 3:21 p.m.