Package {dtComb}

Title: Statistical Combination of Diagnostic Tests
Description: A system for combining two diagnostic tests using various approaches that include statistical and machine-learning-based methodologies. These approaches are divided into four groups: linear combination methods, non-linear combination methods, mathematical operators, and machine learning algorithms. See the https://biotools.erciyes.edu.tr/dtComb/ website for more information, documentation, and examples.
Version: 1.0.8
URL: https://github.com/gokmenzararsiz/dtComb
Language: en-US
Depends: R (≥ 3.5.0)
Imports: pROC (≥ 1.18.0), caret, epiR, gam, ggplot2, ggpubr, glmnet, OptimalCutpoints
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.3.3
NeedsCompilation: no
Packaged: 2026-06-24 14:44:24 UTC; serrailaydayerlitas
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition: 3
VignetteBuilder: knitr
Author: Serra Ilayda Yerlitas Tastan [aut, ctb], Serra Bersan Gengec [aut, ctb], Necla Kochan [aut, ctb], Gozde Erturk Zararsiz [aut, ctb], Selcuk Korkmaz [aut, ctb], Gokmen Zararsiz [aut, ctb, cre]
Maintainer: Gokmen Zararsiz <gokmen.zararsiz@gmail.com>
Repository: CRAN
Date/Publication: 2026-06-24 15:10:08 UTC

dtComb: A Comprehensive R Package for Combining Diagnostic Tests

Description

The dtComb package provides tools to calculate combination scores of two biomarkers, categorized into four main types:

Author(s)

Maintainer: Gokmen Zararsiz gokmen.zararsiz@gmail.com [contributor]

Authors:

See Also

Useful links:

Machine learning model table for mlComb() Includes machine learning models used for the mlComb function

Description

Machine learning model table for mlComb() Includes machine learning models used for the mlComb function

Usage

data(allMethods)

Format

A data frame with 113 rows and 2 variables:

Method

Valid name for the function

Model

Model name

Examples

data(allMethods)
allMethods

Available classification/regression methods in dtComb

Description

This function returns a data.frame of available classification methods in dtComb. These methods are imported from the caret package.

Usage

availableMethods()

Value

No return value contains the method names and explanations of the machine-learning models available for the dtComb package.

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples


availableMethods()

Biomarker data from carriers of a rare genetic disorder A data set containing the carriers of a rare genetic disorder for 120 samples.

Description

Biomarker data from carriers of a rare genetic disorder A data set containing the carriers of a rare genetic disorder for 120 samples.

Usage

data(exampleData2)

Format

A data frame with 120 rows and 5 variables:

Group

Indicator whether the person is a carrier; values: "carriers" and "normals".

m1

Biomarker 1, 1. measurement blood sample

m2

Biomarker 2, 2. measurement blood sample

m3

Biomarker 3, 3. measurement blood sample

m4

Biomarker 4, 4. measurement blood sample

Examples

data(exampleData2)
exampleData2$Group <- factor(exampleData2$Group)
gcol <- c("#E69F00", "#56B4E9")
plot(exampleData2$m1, exampleData2$m2,
  col = gcol[as.numeric(exampleData2$Group)]
)

Simulated data with healthy and diseased individuals A simulation data containing 250 diseased and 250 healthy individuals.

Description

Simulated data with healthy and diseased individuals A simulation data containing 250 diseased and 250 healthy individuals.

Usage

data(exampleData3)

Format

A data frame with 500 rows and 3 variables:

status

Indicator of one's condition, values healthy and diseased

marker1

1. biomarker

marker2

2. biomarker

Examples

data(exampleData3)
exampleData3$status <- factor(exampleData3$status)
gcol <- c("#E69F00", "#56B4E9")
plot(exampleData3$marker1, exampleData3$marker2,
  col = gcol[as.numeric(exampleData3$status)]
)

Helper function for PCL method.

Description

The helper_PCL function estimates the optimized value of given biomarkers for the PCL method.

Usage

helper_PCL(lambda, neg.set, pos.set)

Arguments

lambda

a numeric parameter that will be estimated in minmax method for the combination score

neg.set

a numeric data frame that contains the observation with negative status

pos.set

a numeric data frame that contains the observation with positive status

Value

A numeric value for the estimated optimized value

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples

# call data
data(laparotomy)

# define the function parameters
markers <- cbind(laparotomy$ddimer, laparotomy$log_leukocyte)
status <- factor(laparotomy$group, levels = c("not_needed", "needed"))

neg.set <- markers[status == levels(status)[1], ]
pos.set <- markers[status == levels(status)[2], ]

lambda <- 0.5

stat <- helper_PCL(lambda, neg.set = neg.set, pos.set = pos.set)

Helper function for PT method.

Description

The helper_PT function estimates the optimized value of given biomarkers for the PT method.

Usage

helper_PT(lambda, neg.set, pos.set)

Arguments

lambda

a numeric parameter that will be estimated in minmax method for the combination score

neg.set

a numeric data frame that contains the observation with negative status

pos.set

a numeric data frame that contains the observation with positive status

Value

A numeric value for the estimated optimized value

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples

# call data
data(laparotomy)

# define the function parameters
markers <- cbind(laparotomy$ddimer, laparotomy$log_leukocyte)
status <- factor(laparotomy$group, levels = c("not_needed", "needed"))

neg.set <- markers[status == levels(status)[1], ]
pos.set <- markers[status == levels(status)[2], ]

lambda <- 0.5

stat <- helper_PT(lambda, neg.set = neg.set, pos.set = pos.set)

Helper function for TS method.

Description

The helper_TS function calculates the combination coefficient and optimized value of given biomarkers for the TS method.

Usage

helper_TS(theta, markers, status)

Arguments

theta

a numeric parameter that will be estimated in TS method for the combination score

markers

a numeric data frame that contains the biomarkers

status

a factor data frame that includes the actual disease status of the patients

Value

A numeric Optimized value calculated with combination scores using theta

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples

# call data
data(laparotomy)

# define the function parameters
markers <- cbind(laparotomy$ddimer, laparotomy$log_leukocyte)
status <- factor(laparotomy$group, levels = c("not_needed", "needed"))

t <- 0.5

stat <- helper_TS(theta = t, markers = markers, status = status)

Helper function for minimax method.

Description

The helper_minimax function calculates the combination coefficient and optimized value of given biomarkers for the minimax method.

Usage

helper_minimax(t, neg.set, pos.set, markers, status)

Arguments

t

a numeric parameter that will be estimated in minimax method for the combination score

neg.set

a numeric data frame that contains the observation with negative status

pos.set

a numeric data frame that contains the observation with positive status

markers

a numeric data frame that contains the biomarkers

status

a factor data frame that includes the actual disease status of the patients

Value

A numeric Optimized value calculated with combination scores using t

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples

# call data
data(laparotomy)

# define the function parameters
markers <- cbind(laparotomy$ddimer, laparotomy$log_leukocyte)
status <- factor(laparotomy$group, levels = c("not_needed", "needed"))

neg.set <- markers[status == levels(status)[1], ]
pos.set <- markers[status == levels(status)[2], ]

t <- 0.5

stat <- helper_minimax(t,
  neg.set = neg.set, pos.set = pos.set,
  markers = markers, status
)

Helper function for minmax method.

Description

The helper_minmax function estimates optimized value of given biomarkers for the minmax method.

Usage

helper_minmax(lambda, neg.set, pos.set)

Arguments

lambda

a numeric parameter that will be estimated in minmax method for the combination score

neg.set

a numeric data frame that contains the observations with negative status

pos.set

a numeric data frame that contains the observations with positive status

Value

A numeric value for the estimated optimized value

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples

# call data
data(laparotomy)

# define the function parameters
markers <- cbind(laparotomy$ddimer, laparotomy$log_leukocyte)
status <- factor(laparotomy$group, levels = c("not_needed", "needed"))

neg.set <- markers[status == levels(status)[1], ]
pos.set <- markers[status == levels(status)[2], ]

lambda <- 0.5

stat <- helper_minmax(lambda, neg.set = neg.set, pos.set = pos.set)

Calculate Cohen's kappa and accuracy.

Description

The kappa.accuracy calculates Cohen's kappa and accuracy.

Usage

## S3 method for class 'accuracy'
kappa(DiagStatCombined)

Arguments

DiagStatCombined

a numeric table of confusion matrix of the calculated combination score.

Value

A list of Cohen's kappa and accuracy values

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Diagnostic laparotomy dataset A data set containing the results of diagnostic laparotomy procedures for 225 patients.

Description

Examples data for the dtComb package

Usage

data(laparotomy)

Format

A data frame with 225 rows and 3 variables:

group

Indicator whether the procedure was needed; values: "needed" or "not_needed".

ddimer

Biomarker 1, D-Dimer protein level in blood, ng/mL

log_leukocyte

Biomarker 2, Logarithm of Leukocyte count in blood, per mcL

Examples

data(laparotomy)
laparotomy$group <- factor(laparotomy$group)
gcol <- c("#E69F00", "#56B4E9")
plot(laparotomy$ddimer, laparotomy$log_leukocyte,
  col = gcol[as.numeric(laparotomy$group)]
)

Linear Combination Methods for Diagnostic Test Scores

Description

The linComb function calculates the combination scores of two diagnostic tests selected among several linear combination methods and standardization options.

Usage

linComb(
  markers = NULL,
  status = NULL,
  event = NULL,
  method = c("scoring", "SL", "logistic", "minmax", "PT", "PCL", "minimax", "TS"),
  resample = c("none", "cv", "repeatedcv", "boot"),
  nfolds = 5,
  nrepeats = 3,
  niters = 10,
  standardize = c("none", "min_max_scale", "zScore", "tScore", "scale_mean_to_one",
    "scale_sd_to_one"),
  ndigits = 0,
  show.plot = TRUE,
  direction = c("<", ">"),
  conf.level = 0.95,
  cutoff.method = c("CB", "MCT", "MinValueSp", "MinValueSe", "ValueSp", "ValueSe",
    "MinValueSpSe", "MaxSp", "MaxSe", "MaxSpSe", "MaxProdSpSe", "ROC01", "SpEqualSe",
    "Youden", "MaxEfficiency", "Minimax", "MaxDOR", "MaxKappa", "MinValueNPV",
    "MinValuePPV", "ValueNPV", "ValuePPV", "MinValueNPVPPV", "PROC01", "NPVEqualPPV",
    "MaxNPVPPV", "MaxSumNPVPPV", "MaxProdNPVPPV", "ValueDLR.Negative",
    "ValueDLR.Positive", "MinPvalue", "ObservedPrev", "MeanPrev", "PrevalenceMatching"),
  show.result = FALSE,
  ...
)

Arguments

markers

a numeric a numeric data frame that includes two diagnostic tests results

status

a factor vector that includes the actual disease status of the patients

event

a character string that indicates the event in the status to be considered as positive event

method

a character string specifying the method used for combining the markers.
Notations: Before getting into these methods, let us first introduce some notations that will be used throughout this vignette. Let D_i, i = 1, 2, \ldots, n_1 be the marker values of i\text{th} individual in diseased group, where D_i = (D_{i1}, D_{i2}) and H_j, j=1,2, \ldots, n_2 be the marker values of j\text{th} individual in healthy group, where H_j = H_{j1}, H_{j2}. Let x_i1 = c(D_{i1}, H_{j1}) be the values of the first marker, and x_i2 = c(D_{i2}, H_{j2}) be values of the second marker for the i\text{th} individual i= 1,2, \ldots, n. Let D_{i,min} = min(D_{i1}, D_{i2}), D_{i,max} = max(D_{i1}, D_{i2}) , H_{j,min} = min(H_{j1}, H_{j2}), H_{j,max} = max(H_{j1}, H_{j2}) and c_i be be the resulting combination score for the i\text{th} individual.

The available methods are:

  • Logistic Regression (logistic): Combination score obtained by fitting a logistic regression modelis as follows:

    c_i = \left(\frac{e^ {\beta_0 + \beta_1 x_{i1} + \beta_2 x_{i2}}}{1 + e^{\beta_0 + \beta_1 x_{i1} + \beta_2 x_{i2}}}\right)

    A combination score obtained by fitting a logistic regression model typically refers to the predicted probability or score assigned to each observation in a dataset based on the logistic regression model’s fitted values

  • Scoring based on Logistic Regression (scoring): Combination score is obtained using the slope values of the relevant logistic regression model, slope values are rounded to the number of digits taken from the user.

    c_i = \beta_1 x_{i1} + \beta_2 x_{i2}

  • Pepe & Thompson’s method (PT): The Pepe and Thompson combination score, developed using their optimal linear combination technique, aims to maximize the Mann-Whitney statistic in the same way that the Min-max method does. Unlike the Min-max method, the Pepe and Thomson method takes into account all marker values instead of just the lowest and maximum values.

    maximize\; U(\alpha) = \left(\frac{1}{n_1,n_2}\right) {\sum_{i=1}^{n_1} {\sum_{j=1}^{n_2}}I(D_{i1} + \alpha D_{i2} >= H_{j1} + \alpha H_{j2})}


    c_i = x_{i1} + \alpha x_{i2}

  • Pepe, Cai & Langton’s method (PCL): Pepe, Cai and Langton combination score obtained by using AUC as the parameter of a logistic regression model.

    maximize\; U(\alpha) = \left(\frac{1}{n_1,n_2}\right) {\sum_{i=1}^{n_1} {\sum_{j=1}^{n_2}}I(D_{i1} + \alpha D_{i2} >}

    H_{j1} + \alpha H_{j2}) + \left(\frac{1}{2} \right) I(D_{i1} + \alpha D_{i2} = H_{j1} + \alpha H_{j2})

  • Min-Max method (minmax): This method linearly combines the minimum and maximum values of the markers by finding a parameter,\alpha , that maximizes the Mann-Whitney statistic, an empirical estimate of the ROC area.

    maximize\;U( \alpha ) = \left(\frac{1}{n_1,n_2}\right) {\sum_{i=1}^{n_1} {\sum_{j=1}^{n_2}}I(D_{i,max} + \alpha D_{i,min} > H_{j,max} + \alpha H_{j,min})}


    c_i = x_{i,max} + \alpha x_{i,min}

    where x_{i,max} = max(x_{i1},x_{i2}) and x_{i,min} = min(x_{i1}, x_{i2})

  • Su & Liu’s method (SL): The Su and Liu combination score is computed through Fisher’s discriminant coefficients, which assumes that the underlying data follow a multivariate normal distribution, and the covariance matrices across different classes are assumed to be proportional.Assuming that D\sim N(\mu_D,\textstyle \sum_D) and H\sim N(\mu_H,\textstyle \sum_H) represent the multivariate normal distributions for the diseased and non-diseased groups, respectively. The Fisher’s coefficients are as follows:

    (\alpha , \beta) = (\textstyle \sum_{D}+\sum_{H})^{\;-1}\mu

    \text{where} \mu_=\mu_D - \mu_H. \text{The combination score in this case is:}

    c_i = \alpha x_{i1} + \beta x_{i2}

  • Minimax approach (minimax): Combination score obtained with the Minimax procedure; t parameter is chosen as the value that gives the maximum AUC from the combination score. Suppose that D follows a multivariate normal distribution D\sim N(\mu_D,\textstyle \sum_D), representing diseased group and H follows a multivariate normal distribution H\sim N(\mu_H,\textstyle \sum_H) , representing the non-diseased group. Then Fisher’s coefficients are as follows:

    (\alpha , \beta) = {[t { \textstyle \sum_{D}} + (1 - t) \textstyle \sum_{H}] ^ {-1}}{(\mu_D - \mu_H)}

    c_i = b_1 x_1 + b_2 x_2

  • Todor & Saplacan’s method (TS):Combination score obtained by using the trigonometric functions of the \Theta value that optimizes the corresponding AUC.

    c_i = sin(\theta) x_{i1} + cos(\theta) x_{i2}

resample

a character string indicating the name of the resampling options. Bootstrapping Cross-validation and repeated cross-validation are given as the options for resampling, along with the number of folds and number of repeats.

  • boot: Bootstrapping is performed similarly; the dataset is divided into folds with replacement and models are trained and tested in these folds to determine the best parameters for the given method and dataset.

  • cv: Cross-validation resampling, the dataset is divided into the number of folds given without replacement; in each iteration, one fold is selected as the test set, and the model is built using the remaining folds and tested on the test set. The corresponding AUC values and the parameters used for the combination are kept in a list. The best-performed model is selected, and the combination score is returned for the whole dataset.

  • repeatedcv: Repeated cross-validation the process is repeated, and the best-performed models selected at each step are stored in another list; the best performed among these models is selected to be applied to the entire dataset.

nfolds

a numeric value that indicates the number of folds for cross validation based resampling methods (5, default)

nrepeats

a numeric value that indicates the number of repeats for "repeatedcv" option of resampling methods (3, default)

niters

a numeric value that indicates the number of bootstrapped resampling iterations (10, default)

standardize

a character string indicating the name of the standardization method. The default option is no standardization applied. Available options are:

  • Z-score (zScore): This method scales the data to have a mean of 0 and a standard deviation of 1. It subtracts the mean and divides by the standard deviation for each feature. Mathematically,

    Z-score = \frac{x - (\overline x)}{sd(x)}

    where x is the value of a marker, \overline{x} is the mean of the marker and sd(x) is the standard deviation of the marker.

  • T-score (tScore): T-score is commonly used in data analysis to transform raw scores into a standardized form. The standard formula for converting a raw score x into a T-score is:

    T-score = \Biggl(\frac{x - (\overline x)}{sd(x)}\times 10 \Biggl) +50

    where x is the value of a marker, \overline{x} is the mean of the marker and sd(x) is the standard deviation of the marker.

  • min_max_scale (min_max_scale): This method transforms data to a specific scale, between 0 and 1. The formula for this method is:

    min_max_scale = \frac{x - min(x)}{max(x) - min(x)}

  • scale_mean_to_one (scale_mean_to_one): This method scales the arithmetic mean to 1. The formula for this method is:

    scale_mean_to_one = \frac{x}{\overline{x}}

    where x is the value of a marker and \overline{x} is the mean of the marker.

  • scale_sd_to_one (scale_sd_to_one): This method, which allows for comparison of individual data points in relation to the overall spread of the data, scales the standard deviation to 1. The formula for this method is:

    scale_sd_to_one = \frac{x}{sd(x)}

    where x is the value of a marker and sd(x) is the standard deviation of the marker.

ndigits

a integer value to indicate the number of decimal places to be used for rounding in Scoring method (0, default)

show.plot

a logical. If TRUE, a ROC curve is plotted. Default is TRUE

direction

a character string determines in which direction the comparison will be made. ">": if the predictor values for the control group are higher than the values of the case group (controls > cases). "<": if the predictor values for the control group are lower or equal than the values of the case group (controls < cases).

conf.level

a numeric values determines the confidence interval for the roc curve(0.95, default).

cutoff.method

a character string determines the cutoff method for the roc curve.

show.result

a logical value indicating whether the results should be printed to the console.

...

further arguments. Currently has no effect on the results.

Value

A list of numeric linear combination scores calculated according to the given method and standardization option.

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples

# call data
data(laparotomy)

# define the function parameters
markers <- laparotomy[, -1]
status <- factor(laparotomy$group, levels = c("not_needed", "needed"))
event <- "needed"

score1 <- linComb(
  markers = markers, status = status, event = event,
  method = "logistic", resample = "none", show.plot = TRUE,
  standardize = "none", direction = "<", cutoff.method = "Youden"
)

# call data
data(exampleData2)

# define the function parameters
markers <- exampleData2[, -c(1:3, 6:7)]
status <- factor(exampleData2$Group, levels = c("normals", "carriers"))
event <- "carriers"

score2 <- linComb(
  markers = markers, status = status, event = event,
  method = "PT", resample = "none", standardize = "none", direction = "<",
  cutoff.method = "Youden", show.result = TRUE
)

score3 <- linComb(
  markers = markers, status = status, event = event,
  method = "minmax", resample = "none", direction = "<",
  cutoff.method = "Youden"
)

Combine two diagnostic tests with several mathematical operators and distance measures.

Description

The mathComb function returns the combination results of two diagnostic tests with different mathematical operators, distance measures, standardization, and transform options.

Usage

mathComb(
  markers = NULL,
  status = NULL,
  event = NULL,
  method = c("add", "multiply", "divide", "subtract", "distance", "baseinexp",
    "expinbase"),
  distance = c("euclidean", "manhattan", "chebyshev", "kulczynski_d", "lorentzian",
    "avg", "taneja", "kumar-johnson"),
  standardize = c("none", "min_max_scale", "zScore", "tScore", "scale_mean_to_one",
    "scale_sd_to_one"),
  transform = c("none", "log", "exp", "sin", "cos"),
  show.plot = TRUE,
  direction = c("<", ">"),
  conf.level = 0.95,
  cutoff.method = c("CB", "MCT", "MinValueSp", "MinValueSe", "ValueSp", "ValueSe",
    "MinValueSpSe", "MaxSp", "MaxSe", "MaxSpSe", "MaxProdSpSe", "ROC01", "SpEqualSe",
    "Youden", "MaxEfficiency", "Minimax", "MaxDOR", "MaxKappa", "MinValueNPV",
    "MinValuePPV", "ValueNPV", "ValuePPV", "MinValueNPVPPV", "PROC01", "NPVEqualPPV",
    "MaxNPVPPV", "MaxSumNPVPPV", "MaxProdNPVPPV", "ValueDLR.Negative",
    "ValueDLR.Positive", "MinPvalue", "ObservedPrev", "MeanPrev", "PrevalenceMatching"),
  show.result = FALSE,
  ...
)

Arguments

markers

a numeric data frame that includes two diagnostic tests results

status

a factor vector that includes the actual disease status of the patients

event

a character string that indicates the event in the status to be considered as positive event

method

a character string specifying the method used for combining the markers. The available methods are:

  • add: Combination score obtained by adding markers

  • multiply: Combination score obtained by multiplying markers

  • divide: Combination score obtained by dividing markers

  • subtract: Combination score obtained by subtracting markers

  • distance: Combination score obtained with the help of distance measures.

  • baseinexp: Combination score obtained by marker1 power marker2.

  • expinbase: Combination score obtained by marker2 power marker1.

distance

a character string specifying the method used for combining the markers. The available methods are:

  • Euclidean (euclidean): c_i = {\sqrt{(x_{i1}-0)^2+(x_{i2}-0)^2}}

  • Manhattan(manhattan): c_i = |x_{i1}-0|+|x_{i2}-0|

  • Chebyshev (chebyshev): c_i = max{|x_{i1}-0|,|x_{i2}-0|}

  • Kulczynski (kulczynski_d): c_i = \frac{|x_{i1}-0|+|x_{i2}-0|}{min(x_{i1},x_{i2})}

  • Lorentzian (lorentzian): c_i = (ln(1+|x_{i1}-0|))+ (ln(1+|x_{i2}-0|))

  • Taneja (taneja): c_i = z_1\times\Biggl(log\frac{z_1}{\sqrt{(x_{i1}\times \epsilon )}}\Biggl)+z_2\times\Biggl(log\frac{z_2}{\sqrt{(x_{i2}\times\epsilon)}}\Biggl)

  • Kumar-Johnson (kumar-johnson): c_i = {\frac{(x_{i1}-0)^2}{2(x_{i1}\times\epsilon)}}+{\frac{(x_{i2}-0)^2}{2(x_{i2}\times\epsilon)}}, \epsilon = 0.00001

  • Avg (avg):

    (L_1, L_n) = \frac{|x_{i1}-0|+|x_{i2}-0| + max{(x_{i1}-0),(x_{i2}-0)}}{2}

standardize

a character string indicating the name of the standardization method. The default option is no standardization applied. Available options are:

  • Z-score (zScore): This method scales the data to have a mean of 0 and a standard deviation of 1. It subtracts the mean and divides by the standard deviation for each feature. Mathematically,

    Z-score = \frac{x - (\overline x)}{sd(x)}

    where x is the value of a marker, \overline{x} is the mean of the marker and sd(x) is the standard deviation of the marker.

  • T-score (tScore): T-score is commonly used in data analysis to transform raw scores into a standardized form. The standard formula for converting a raw score x into a T-score is:

    T-score = \Biggl(\frac{x - (\overline x)}{sd(x)}\times 10 \Biggl) +50

    where x is the value of a marker, \overline{x} is the mean of the marker and sd(x) is the standard deviation of the marker.

  • min_max_scale (min_max_scale): This method transforms data to a specific scale, between 0 and 1. The formula for this method is:

    min_max_scale = \frac{x - min(x)}{max(x) - min(x)}

  • scale_mean_to_one (scale_mean_to_one): This method scales the arithmetic mean to 1. The formula for this method is:

    scale_mean_to_one = \frac{x}{\overline{x}}

    where x is the value of a marker and \overline{x} is the mean of the marker.

  • scale_sd_to_one (scale_sd_to_one): This method, which allows for comparison of individual data points in relation to the overall spread of the data, scales the standard deviation to 1. The formula for this method is:

    scale_sd_to_one = \frac{x}{sd(x)}

    where x is the value of a marker and sd(x) is the standard deviation of the marker.

transform

A character string specifying the mathematical transformation method. Available options: "log", "exp", "sin", "cos".

  • log: Applies logarithm transform to markers before calculating combination score

  • exp: Applies exponential transform to markers before calculating combination score

  • sin: Applies sinus trigonometric transform to markers before calculatin combination score

  • cos: Applies cosinus trigonometric transform to markers before calculating combination score

show.plot

a logical. If TRUE, a ROC curve is plotted. Default is TRUE

direction

a character string determines in which direction the comparison will be made. ">": if the predictor values for the control group are higher than the values of the case group (controls > cases). "<": if the predictor values for the control group are lower or equal than the values of the case group (controls < cases).

conf.level

a numeric values determines the confidence interval for the roc curve(0.95, default).

cutoff.method

a character string determines the cutoff method for the roc curve.

show.result

A logical value indicating whether the results should be printed to the console.

...

further arguments. Currently has no effect on the results.

Value

A list containing the computed combination scores and, optionally, diagnostic performance metrics.

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples


data(laparotomy)
markers <- laparotomy[, -1]
status <- factor(laparotomy$group, levels = c("not_needed", "needed"))
event <- "needed"
direction <- "<"
cutoff.method <- "Youden"

score1 <- mathComb(
  markers = markers, status = status, event = event,
  method = "distance", distance = "avg", direction = direction, show.plot = FALSE,
  standardize = "none", cutoff.method = cutoff.method
)

score2 <- mathComb(
  markers = markers, status = status, event = event,
  method = "baseinexp", transform = "exp", direction = direction,
  cutoff.method = cutoff.method
)

score3 <- mathComb(
  markers = markers, status = status, event = event,
  method = "subtract", direction = "<", cutoff.method = "MinValueSp", transform = "sin"
)

Combine two diagnostic tests with Machine Learning Algorithms.

Description

The mlComb function calculates the combination scores of two diagnostic tests selected among several Machine Learning Algorithms

Usage

mlComb(
  markers = NULL,
  status = NULL,
  event = NULL,
  method = NULL,
  resample = NULL,
  niters = 10,
  nfolds = 5,
  nrepeats = 3,
  preProcess = NULL,
  show.plot = TRUE,
  B = 25,
  direction = c("<", ">"),
  conf.level = 0.95,
  p = 0.75,
  cutoff.method = c("CB", "MCT", "MinValueSp", "MinValueSe", "ValueSp", "ValueSe",
    "MinValueSpSe", "MaxSp", "MaxSe", "MaxSpSe", "MaxProdSpSe", "ROC01", "SpEqualSe",
    "Youden", "MaxEfficiency", "Minimax", "MaxDOR", "MaxKappa", "MinValueNPV",
    "MinValuePPV", "ValueNPV", "ValuePPV", "MinValueNPVPPV", "PROC01", "NPVEqualPPV",
    "MaxNPVPPV", "MaxSumNPVPPV", "MaxProdNPVPPV", "ValueDLR.Negative",
    "ValueDLR.Positive", "MinPvalue", "ObservedPrev", "MeanPrev", "PrevalenceMatching"),
  show.result = FALSE,
  ...
)

Arguments

markers

a numeric data frame that includes two diagnostic tests results

status

a factor vector that includes the actual disease status of the patients

event

a character string that indicates the event in the status to be considered as positive event

method

a character string specifying the method used for combining the markers. For the available methods see availableMethods()

IMPORTANT: See https://topepo.github.io/caret/available-models.html for further information about the methods used in this function.

resample

A character string specifying the resampling method used while training the model. Available methods are "boot", "boot632", "optimism_boot", "boot_all", "cv", "repeatedcv", "LOOCV", "LGOCV", "none", "oob", "adaptive_cv", "adaptive_boot", and "adaptive_LGOCV". The "timeslice" method is not supported by mlComb. If NULL, "none" is used.

niters

A positive integer indicating the number of bootstrap resampling iterations. Used for "boot", "boot632", "optimism_boot", "boot_all", and "adaptive_boot". Default is 10.

nfolds

A positive integer. For "cv", "repeatedcv", and "adaptive_cv", it indicates the number of folds. For "LGOCV" and "adaptive_LGOCV", it indicates the number of repeated training/test splits. Default is 5.

nrepeats

A positive integer indicating the number of repeats for "repeatedcv". Default is 3.

preProcess

a character string that indicates the pre-processing options to be applied in the data before training the model. Available pre-processing methods are: "BoxCox", "YeoJohnson", "expoTrans", "center", "scale", "range", "knnImpute", "bagImpute", "medianImpute", "pca", "ica", "spatialSign", "corr", "zv", "nzv", and "conditionalX". For detailed information about the methods see ?caret::preProcess

show.plot

a logical. If TRUE, a ROC curve is plotted. Default is TRUE

B

a numeric value that is the number of bootstrap samples for bagging classifiers, "bagFDA", "bagFDAGCV", "bagEarth" and "bagEarthGCV". (25, default)

direction

a character string determines in which direction the comparison will be made. ">": if the predictor values for the control group are higher than the values of the case group (controls > cases). "<": if the predictor values for the control group are lower or equal than the values of the case group (controls < cases).

conf.level

a numeric value to determine the confidence interval for the ROC curve(0.95, default).

p

A numeric value between 0 and 1 specifying the training proportion used for "LGOCV" and "adaptive_LGOCV". Default is 0.75.

cutoff.method

a character string determines the cutoff method for the ROC curve.

show.result

a logical string indicating whether the results should be printed to the console.

...

optional arguments passed to selected classifiers.

Value

A list of AUC values, diagnostic statistics, coordinates of the ROC curve for the combination score obtained using Machine Learning Algorithms as well as the given biomarkers individually, a comparison table for the AUC values of individual biomarkers and combination score obtained and the fitted model.

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

See Also

availableMethods, caret::train, caret::trainControl

Examples

# call data
data(laparotomy)

# define the function parameters
markers <- laparotomy[, -1]
status <- factor(laparotomy$group, levels = c("not_needed", "needed"))
event <- "needed"

model <- mlComb(
  markers = markers, status = status, event = event,
  method = "knn", resample = "cv", nfolds = 5,
  preProcess = c("center", "scale"), direction = "<", cutoff.method = "Youden"
)

Combine two diagnostic tests with several non-linear combination methods.

Description

The nonlinComb function calculates the combination scores of two diagnostic tests selected among several non-linear combination methods and standardization options

Usage

nonlinComb(
  markers = NULL,
  status = NULL,
  event = NULL,
  method = c("polyreg", "ridgereg", "lassoreg", "elasticreg", "splines", "sgam", "nsgam"),
  degree1 = 3,
  degree2 = 3,
  df1 = 4,
  df2 = 4,
  resample = c("none", "cv", "repeatedcv", "boot"),
  nfolds = 5,
  nrepeats = 3,
  niters = 10,
  standardize = c("none", "min_max_scale", "zScore", "tScore", "scale_mean_to_one",
    "scale_sd_to_one"),
  include.interact = FALSE,
  alpha = 0.5,
  show.plot = TRUE,
  direction = c("<", ">"),
  conf.level = 0.95,
  cutoff.method = c("CB", "MCT", "MinValueSp", "MinValueSe", "ValueSp", "ValueSe",
    "MinValueSpSe", "MaxSp", "MaxSe", "MaxSpSe", "MaxProdSpSe", "ROC01", "SpEqualSe",
    "Youden", "MaxEfficiency", "Minimax", "MaxDOR", "MaxKappa", "MinValueNPV",
    "MinValuePPV", "ValueNPV", "ValuePPV", "MinValueNPVPPV", "PROC01", "NPVEqualPPV",
    "MaxNPVPPV", "MaxSumNPVPPV", "MaxProdNPVPPV", "ValueDLR.Negative",
    "ValueDLR.Positive", "MinPvalue", "ObservedPrev", "MeanPrev", "PrevalenceMatching"),
  show.result = FALSE,
  ...
)

Arguments

markers

a numeric data frame that includes two diagnostic tests results

status

a factor vector that includes the actual disease status of the patients

event

a character string that indicates the event in the status to be considered as positive event

method

a character string specifying the method used for combining the markers. The available methods are:

  • Logistic Regression with Polynomial Feature Space (polyreg): The method builds a logistic regression model with the polynomial feature space and returns the probability of a positive event for each observation.

  • Ridge Regression with Polynomial Feature Space (ridgereg): Ridge regression is a shrinkage method used to estimate the coefficients of highly correlated variables and in this case the polynomial feature space created from two markers. For the implementation of the method, glmnet() library is used with two functions: cv.glmnet() to run a cross validation model to determine the tuning parameter \lambda and glmnet() to fit the model with the selected tuning parameter. For Ridge regression, the glmnet() package is integrated into the dtComb package to facilitate the implementation of this method.

  • Lasso Regression with Polynomial Feature Space (lassoreg): Lasso regression, like Ridge regression, is a type of shrinkage method. However, a notable difference is that Lasso tends to set some feature coefficients to zero, making it useful for feature elimination. It also employs cross-validation for parameter selection and model fitting using the glmnet library.

  • Elastic Net Regression with Polynomial Feature Space (elasticreg): Elastic Net regression is a hybrid model that merges the penalties from Ridge and Lasso regression, aiming to leverage the strengths of both approaches. This model involves two parameters: \lambda, similar to Ridge and Lasso, and \alpha, a user-defined mixing parameter ranging between 0 (representing Ridge) and 1 (representing Lasso). The \alpha parameter determines the balance or weights between the loss functions of Ridge and Lasso regressions.

  • Splines (splines): Another non-linear approach to combine markers involves employing regression models within a polynomial feature space. This approach applies multiple regression models to the dataset using a function derived from piecewise polynomials. This implementation uses splines with user-defined degrees of freedom and degrees for the fitted polynomials. The splines library is employed to construct piecewise logistic regression models using base splines.

  • Generalized Additive Models with Smoothing Splines and Generalized Additive Models with Natural Cubic Splines (sgam & nsgam): In addition to the basic spline structure, Generalized Additive Models are applied with natural cubic splines and smoothing splines using the gam library in R.

degree1

a numeric value for polynomial based methods indicates the degree of the feature space created for marker 1, for spline based methods the degree of the fitted polynomial between each node for marker 1. (3, default)

degree2

a numeric value for polynomial based methods indicates the degree of the feature space created for marker 2, for spline based methods the degree of the fitted polynomial between each node for marker 2 (3, default)

df1

a numeric value that indicates the number of knots as the degrees of freedom in spline based methods for marker 1 (4, default)

df2

a numeric value that indicates the number of knots as the degrees of freedom in spline based methods for marker 2 (4, default)

resample

a character string indicating the name of the resampling options. Bootstrapping Cross-validation and repeated cross-validation are given as the options for resampling, along with the number of folds and number of repeats.

  • boot: Bootstrapping is performed similarly; the dataset is divided into folds with replacement and models are trained and tested in these folds to determine the best parameters for the given method and dataset.

  • cv: Cross-validation resampling, the dataset is divided into the number of folds given without replacement; in each iteration, one fold is selected as the test set, and the model is built using the remaining folds and tested on the test set. The corresponding AUC values and the parameters used for the combination are kept in a list. The best-performed model is selected, and the combination score is returned for the whole dataset.

  • repeatedcv: Repeated cross-validation the process is repeated, and the best-performed models selected at each step are stored in another list; the best performed among these models is selected to be applied to the entire dataset.

nfolds

a numeric value that indicates the number of folds for cross validation based resampling methods (5, default)

nrepeats

a numeric value that indicates the number of repeats for "repeatedcv" option of resampling methods (3, default)

niters

a numeric value that indicates the number of bootstrapped resampling iterations (10, default)

standardize

a character string indicating the name of the standardization method. The default option is no standardization applied. Available options are:

  • Z-score (zScore): This method scales the data to have a mean of 0 and a standard deviation of 1. It subtracts the mean and divides by the standard deviation for each feature. Mathematically,

    Z-score = \frac{x - (\overline x)}{sd(x)}

    where x is the value of a marker, \overline{x} is the mean of the marker and sd(x) is the standard deviation of the marker.

  • T-score (tScore): T-score is commonly used in data analysis to transform raw scores into a standardized form. The standard formula for converting a raw score x into a T-score is:

    T-score = \Biggl(\frac{x - (\overline x)}{sd(x)}\times 10 \Biggl) +50

    where x is the value of a marker, \overline{x} is the mean of the marker and sd(x) is the standard deviation of the marker.

  • min_max_scale (min_max_scale): This method transforms data to a specific scale, between 0 and 1. The formula for this method is:

    min_max_scale = \frac{x - min(x)}{max(x) - min(x)}

  • scale_mean_to_one (scale_mean_to_one): This method scales the arithmetic mean to 1. The formula for this method is:

    scale_mean_to_one = \frac{x}{\overline{x}}

    where x is the value of a marker and \overline{x} is the mean of the marker.

  • scale_sd_to_one (scale_sd_to_one): This method, which allows for comparison of individual data points in relation to the overall spread of the data, scales the standard deviation to 1. The formula for this method is:

    scale_sd_to_one = \frac{x}{sd(x)}

    where x is the value of a marker and sd(x) is the standard deviation of the marker.

include.interact

a logical indicator that specifies whether to include the interaction between the markers to the feature space created for polynomial based methods (FALSE, default)

alpha

a numeric value as the mixing parameter in Elastic Net Regression method (0.5, default)

show.plot

a logical. If TRUE, a ROC curve is plotted. Default is TRUE

direction

a character string determines in which direction the comparison will be made. ">": if the predictor values for the control group are higher than the values of the case group (controls > cases). "<": if the predictor values for the control group are lower or equal than the values of the case group (controls < cases).

conf.level

a numeric values determines the confidence interval for the ROC curve(0.95, default).

cutoff.method

a character string determines the cutoff method for the ROC curve.

show.result

a logical string indicating whether the results should be printed to the console.

...

further arguments. Currently has no effect on the results.

Value

A list of numeric nonlinear combination scores calculated according to the given method and standardization option

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples

data("laparotomy")
data <- laparotomy

markers <- data[, -1]
status <- factor(data$group, levels = c("not_needed", "needed"))
event <- "needed"
cutoff.method <- "Youden"

score1 <- nonlinComb(
  markers = markers, status = status, event = event,
  method = "lassoreg", include.interact = FALSE, resample = "boot", niters = 5,
  degree1 = 4, degree2 = 4, cutoff.method = cutoff.method,
  direction = "<"
)

score2 <- nonlinComb(
  markers = markers, status = status, event = event,
  method = "splines", resample = "none", cutoff.method = cutoff.method,
  standardize = "tScore", direction = "<"
)

score3 <- nonlinComb(
  markers = markers, status = status, event = event,
  method = "lassoreg", resample = "repeatedcv", include.interact = TRUE,
  cutoff.method = "ROC01", standardize = "zScore", direction = "<"
)

Plot the combination scores using the training model

Description

The plotComb a function that generates plots from the training model. The function takes argument model. The outputs of the function are three different plots generated from the combination scores.

Usage

plotComb(model, status)

Arguments

model

a list object where the parameters from the training model are saved.

status

a factor vector that includes the actual disease status of the patients

Value

A data.frame plots

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples


# call data
data(laparotomy)

# define the function parameters
markers <- laparotomy[, -1]
status <- factor(laparotomy$group, levels = c("not_needed", "needed"))
event <- "needed"

score1 <- linComb(
  markers = markers, status = status, event = event,
  method = "scoring", resample = "none",
  standardize = "none", direction = "<", cutoff.method = "Youden"
)

plotComb(score1, status)

score2 <- nonlinComb(
  markers = markers, status = status, event = event,
  method = "nsgam", resample = "cv", include.interact = FALSE, direction = "<",
  standardize = "zScore", cutoff.method = "Youden"
)

plot.score2 <- plotComb(score2, status)

score3 <- mathComb(
  markers = markers, status = status, event = event,
  method = "distance", distance = "euclidean", direction = "<",
  standardize = "tScore", cutoff.method = "Youden"
)

plot.score3 <- plotComb(score3, status)

Predict combination scores and labels for new data sets using the training model

Description

The predict.dtComb is a function that generates predictions for a new dataset of biomarkers using the parameters from the fitted model. The function takes arguments newdata and model. The function's output is the combination scores and labels of object type.

Usage

## S3 method for class 'dtComb'
predict(object, newdata = NULL, ...)

Arguments

object

a list object where the parameters from the training model are saved.

newdata

a numeric new data set that includes biomarkers that have not been introduced to the model before.

...

further arguments. Currently has no effect on the results.

Value

A data.frame predicted combination scores (or probabilities) and labels

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples


# call data
data(laparotomy)

# define the function parameters
markers <- laparotomy[, -1]
status <- factor(laparotomy$group, levels = c("not_needed", "needed"))
event <- "needed"

score1 <- linComb(
  markers = markers, status = status, event = event,
  method = "logistic", resample = "none",
  standardize = "none", direction = "<", cutoff.method = "Youden"
)

comb.score1 <- predict(score1, markers)

score2 <- nonlinComb(
  markers = markers, status = status, event = "needed", include.interact = TRUE,
  method = "polyreg", resample = "repeatedcv", nfolds = 5,
  nrepeats = 10, cutoff.method = "Youden", direction = "<"
)

comb.score2 <- predict(score2, markers)

score3 <- mathComb(
  markers = markers, status = status, event = event,
  method = "distance", distance = "euclidean", direction = "<",
  standardize = "tScore", cutoff.method = "Youden"
)

comb.score3 <- predict(score3, markers)

Description

The print_train function prints the summary statistics of the fitted model

Usage

print_train(print_model)

Arguments

print_model

a list of parameters taken from the fitted model that includes the combination method, resampling method, pre-processing method, selected optimum parameters and the results of fit.

Value

No return value writes a summary of the results to the console.

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Generate ROC curves and related statistics for the given markers and Combination score.

Description

The rocsum function returns the ROC curves with coordinates, Area Under the Curves of markers and combination score, Area Under the Curve comparison of markers and combination score, Confusion matrices for both markers and combination score with the cutoff values derived from the ROC Curves.

Usage

rocsum(
  markers = NULL,
  comb.score = NULL,
  status = NULL,
  event = NULL,
  direction = c("<", ">"),
  conf.level = 0.95,
  cutoff.method = c("CB", "MCT", "MinValueSp", "MinValueSe", "ValueSp", "ValueSe",
    "MinValueSpSe", "MaxSp", "MaxSe", "MaxSpSe", "MaxProdSpSe", "ROC01", "SpEqualSe",
    "Youden", "MaxEfficiency", "Minimax", "MaxDOR", "MaxKappa", "MinValueNPV",
    "MinValuePPV", "ValueNPV", "ValuePPV", "MinValueNPVPPV", "PROC01", "NPVEqualPPV",
    "MaxNPVPPV", "MaxSumNPVPPV", "MaxProdNPVPPV", "ValueDLR.Negative",
    "ValueDLR.Positive", "MinPvalue", "ObservedPrev", "MeanPrev", "PrevalenceMatching"),
  show.plot = show.plot
)

Arguments

markers

a numeric data frame that includes two diagnostic tests results

comb.score

a matrix of numeric combination scores calculated according to the given method

status

a factor vector that includes the actual disease status of the patients

event

a character string that indicates the event in the status to be considered as positive event

direction

a character string determines in which direction the comparison will be made. “>”: if the predictor values for the control group are higher than the values of the case group (controls > cases). “<”: if the predictor values for the control group are lower or equal than the values of the case group (controls < cases).

conf.level

a numeric values determines the confidens interval for the ROC curve(0.95, default).

cutoff.method

a character string determines the cutoff method for the ROC curve.

show.plot

a logical. If TRUE, a ROC curve is plotted. Default is FALSE.

Value

A list of numeric ROC Curves, AUC statistics and Confusion matrices.

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Standardization according to the training model parameters.

Description

The std.test Standardization parameters will be taken from the fitted training model and applied to the new data set.

Usage

std.test(newdata, model)

Arguments

newdata

a numeric data frame of biomarkers

model

a list of parameters from the output of linComb, nonlinComb, mlComb or mathComb functions.

Value

A numeric dataframe of standardized biomarkers

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Standardization according to the chosen method.

Description

The std.train Standardization (min_max_scale, zScore etc.) can be estimated from the training data and applied to any dataset with the same variables.

Usage

std.train(data, standardize = NULL)

Arguments

data

a numeric data frame of biomarkers

standardize

a character string indicating the name of the standardization method. The default option is no standardization applied. Available options are:

  • Z-score (zScore): This method scales the data to have a mean of 0 and a standard deviation of 1. It subtracts the mean and divides by the standard deviation for each feature. Mathematically,

    Z-score = \frac{x - (\overline x)}{sd(x)}

    where x is the value of a marker, \overline{x} is the mean of the marker and sd(x) is the standard deviation of the marker.

  • T-score (tScore): T-score is commonly used in data analysis to transform raw scores into a standardized form. The standard formula for converting a raw score x into a T-score is:

    T-score = \Biggl(\frac{x - (\overline x)}{sd(x)}\times 10 \Biggl) +50

    where x is the value of a marker, \overline{x} is the mean of the marker and sd(x) is the standard deviation of the marker.

  • min_max_scale (min_max_scale): This method transforms data to a specific scale, between 0 and 1. The formula for this method is:

    min_max_scale = \frac{x - min(x)}{max(x) - min(x)}

  • scale_mean_to_one (scale_mean_to_one): This method scales the arithmetic mean to 1. The formula for this method is:

    scale_mean_to_one = \frac{x}{\overline{x}}

    where x is the value of a marker and \overline{x} is the mean of the marker.

  • scale_sd_to_one (scale_sd_to_one): This method, which allows for comparison of individual data points in relation to the overall spread of the data, scales the standard deviation to 1. The formula for this method is:

    scale_sd_to_one = \frac{x}{sd(x)}

    where x is the value of a marker and sd(x) is the standard deviation of the marker.

Value

A numeric data.frame of standardized biomarkers

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples

# call data
data(laparotomy)

# define the function parameters
markers <- laparotomy[, -1]
markers2 <- std.train(markers, "deviance")

Mathematical transformations for biomarkers

Description

Applies a selected mathematical transformation ("log", "exp", "sin", or "cos") to biomarker data.

Usage

transform_math(markers, transform)

Arguments

markers

A numeric data frame that contains the biomarkers.

transform

A character string specifying the transformation method to be applied. Supported methods are: "log", "exp", "sin", "cos".

Value

A numeric data frame containing the transformed biomarkers.

Author(s)

Serra Ilayda Yerlitas Tastan, Serra Bersan Gengec, Necla Kochan, Gozde Erturk Zararsiz, Selcuk Korkmaz, Gokmen Zararsiz

Examples

data(laparotomy)
markers <- laparotomy[, -1]
transform_math(markers, transform = "log")

Validate parameters specific to linComb

Description

Internal helper used by linComb to validate linear-combination-specific arguments. It checks the selected combination method, resampling method, standardization method, and method-specific standardization requirements. It also adjusts nrepeats when resample = "cv" and forces the required standardization for selected methods.

Usage

validateLinComb(
  method = c("scoring", "SL", "logistic", "minmax", "PT", "PCL", "minimax", "TS"),
  resample = c("none", "cv", "repeatedcv", "boot"),
  nfolds = 5,
  nrepeats = 3,
  niters = 10,
  standardize = c("none", "min_max_scale", "zScore", "tScore", "scale_mean_to_one",
    "scale_sd_to_one"),
  ndigits = 0
)

Arguments

method

A character string specifying the linear combination method. Available methods are "scoring", "SL", "logistic", "minmax", "PT", "PCL", "minimax", and "TS".

resample

A character string specifying the resampling method. Available options are "none", "cv", "repeatedcv", and "boot".

nfolds

A positive integer indicating the number of folds for cross-validation-based resampling methods. Default is 5.

nrepeats

A positive integer indicating the number of repeats for "repeatedcv". If resample = "cv", this is set to 1. Default is 3.

niters

A positive integer indicating the number of bootstrap resampling iterations when resample = "boot". Default is 10.

standardize

A character string specifying the standardization method. Available options are "none", "min_max_scale", "zScore", "tScore", "scale_mean_to_one", and "scale_sd_to_one".

ndigits

A non-negative integer indicating the number of decimal places used for rounding coefficients in the "scoring" method. Default is 0.

Details

The "minmax" and "PCL" methods require standardize = "min_max_scale". If another standardization method is supplied, it is replaced with "min_max_scale" and a warning is issued.

The "PT" method requires standardize = "zScore". If another standardization method is supplied, it is replaced with "zScore" and a warning is issued.

Value

A list containing the validated and prepared values: method, resample, nfolds, nrepeats, niters, standardize, and ndigits.

Validate parameters specific to mathComb

Description

Internal helper used by mathComb to validate mathematical-combination specific arguments. It checks the selected mathematical operator, distance metric, standardization method, transformation method, and marker-value requirements for selected transformations.

Usage

validateMathComb(
  markers,
  method = c("add", "multiply", "divide", "subtract", "distance", "baseinexp",
    "expinbase"),
  distance = c("euclidean", "manhattan", "chebyshev", "kulczynski_d", "lorentzian",
    "avg", "taneja", "kumar-johnson"),
  standardize = c("none", "min_max_scale", "zScore", "tScore", "scale_mean_to_one",
    "scale_sd_to_one"),
  transform = c("none", "log", "exp", "sin", "cos")
)

Arguments

markers

A numeric data frame or matrix containing the marker values. Marker values must be finite. If transform = "log", all marker values must be positive. If transform = "exp", transformed values must remain finite.

method

A character string specifying the mathematical combination method. Available methods are "add", "multiply", "divide", "subtract", "distance", "baseinexp", and "expinbase".

distance

A character string specifying the distance metric used when method = "distance". Available options are "euclidean", "manhattan", "chebyshev", "kulczynski_d", "lorentzian", "avg", "taneja", and "kumar-johnson". For non-distance methods, this is set to NULL.

standardize

A character string specifying the standardization method. Available options are "none", "min_max_scale", "zScore", "tScore", "scale_mean_to_one", and "scale_sd_to_one".

transform

A character string specifying the transformation applied to marker values. Available options are "none", "log", "exp", "sin", and "cos".

Value

A list containing the validated and prepared values: standardize and transform.

Validate parameters specific to mlComb

Description

Internal helper used by mlComb to validate machine-learning-specific arguments before fitting the caret model. It checks the selected method, resampling method, resampling control parameters, preprocessing options, bagging parameter, and oob/adaptive resampling restrictions.

Usage

validateMlComb(
  niters = 10,
  nfolds = 5,
  nrepeats = 3,
  preProcess = NULL,
  B = 25,
  p = 0.75,
  resample = "none",
  method = NULL
)

Arguments

niters

A positive integer indicating the number of bootstrap resampling iterations. Used for "boot", "boot632", "optimism_boot", "boot_all", and "adaptive_boot". Default is 10.

nfolds

A positive integer. For "cv", "repeatedcv", and "adaptive_cv", it indicates the number of folds. For "LGOCV" and "adaptive_LGOCV", it indicates the number of repeated training/test splits. Default is 5.

nrepeats

A positive integer indicating the number of repeats for "repeatedcv". Default is 3.

preProcess

A character vector specifying preprocessing methods passed to caret::train. Available options are "BoxCox", "YeoJohnson", "expoTrans", "center", "scale", "range", "knnImpute", "bagImpute", "medianImpute", "pca", "ica", "spatialSign", "corr", "zv", "nzv", and "conditionalX". Default is NULL.

B

A positive integer indicating the number of bootstrap samples for bagging classifiers such as "bagFDA", "bagFDAGCV", "bagEarth", and "bagEarthGCV". Default is 25.

p

A numeric value between 0 and 1 specifying the training proportion used for "LGOCV" and "adaptive_LGOCV". Default is 0.75.

resample

A character string specifying the resampling method. Allowed values are "boot", "boot632", "optimism_boot", "boot_all", "cv", "repeatedcv", "LOOCV", "LGOCV", "none", "oob", "adaptive_cv", "adaptive_boot", and "adaptive_LGOCV". The "timeslice" method is not supported by mlComb.

method

A character string specifying the caret model used by mlComb. It must be available in allMethods[, 1].

Details

The "oob" resampling method is restricted to suitable random forest, bagged tree, bagged earth, bagged flexible discriminant analysis, and conditional tree forest methods.

For "adaptive_cv" and "adaptive_LGOCV", nfolds must be greater than 5. For "repeatedcv", nrepeats must be at least 2.

Value

Invisibly returns TRUE if all checks pass. Otherwise, an error is thrown.

Validate parameters specific to nonlinComb

Description

Internal helper used by nonlinComb to validate nonlinear-combination-specific arguments. It checks the selected nonlinear combination method, polynomial degrees, spline/GAM degrees of freedom, resampling method and related resampling parameters, standardization method, interaction option, and elastic net mixing parameter.

Usage

validateNonlinComb(
  method = c("polyreg", "ridgereg", "lassoreg", "elasticreg", "splines", "sgam", "nsgam"),
  degree1 = 3,
  degree2 = 3,
  df1 = 4,
  df2 = 4,
  resample = c("none", "cv", "repeatedcv", "boot"),
  nfolds = 5,
  nrepeats = 3,
  niters = 10,
  standardize = c("none", "min_max_scale", "zScore", "tScore", "scale_mean_to_one",
    "scale_sd_to_one"),
  include.interact = FALSE,
  alpha = 0.5
)

Arguments

method

A character string specifying the nonlinear combination method. Available methods are "polyreg", "ridgereg", "lassoreg", "elasticreg", "splines", "sgam", and "nsgam".

degree1

A positive integer specifying the polynomial degree for the first marker in polynomial-based methods. Default is 3.

degree2

A positive integer specifying the polynomial degree for the second marker in polynomial-based methods. Default is 3.

df1

A positive integer specifying the degrees of freedom for the first marker in spline/GAM-based methods. Default is 4.

df2

A positive integer specifying the degrees of freedom for the second marker in spline/GAM-based methods. Default is 4.

resample

A character string specifying the resampling method. Available options are "none", "cv", "repeatedcv", and "boot".

nfolds

A positive integer indicating the number of folds for cross-validation-based resampling methods. Default is 5.

nrepeats

A positive integer indicating the number of repeats for "repeatedcv". If resample = "cv", this is set to 1. Default is 3.

niters

A positive integer indicating the number of bootstrap resampling iterations when resample = "boot". Default is 10.

standardize

A character string specifying the standardization method. Available options are "none", "min_max_scale", "zScore", "tScore", "scale_mean_to_one", and "scale_sd_to_one".

include.interact

A logical value indicating whether the interaction term between the two markers should be included in polynomial-based methods. Default is FALSE.

alpha

A numeric value between 0 and 1 specifying the elastic net mixing parameter when method = "elasticreg". Default is 0.5.

Value

A list containing the validated and prepared values: method, degree1, degree2, df1, df2, resample, nfolds, nrepeats, niters, standardize, include.interact, and alpha.

Validate and prepare common diagnostic-combination parameters

Description

Internal helper used to validate and prepare parameters shared by diagnostic combination functions. It checks marker data, disease status, event class, ROC direction, confidence level, cutoff method, and display options. It also converts markers to a data frame and status to a factor when needed.

Usage

validateParameters(
  markers = NULL,
  status = NULL,
  event = NULL,
  method = NULL,
  direction = c("<", ">"),
  conf.level = 0.95,
  cutoff.method = c("CB", "MCT", "MinValueSp", "MinValueSe", "ValueSp", "ValueSe",
    "MinValueSpSe", "MaxSp", "MaxSe", "MaxSpSe", "MaxProdSpSe", "ROC01", "SpEqualSe",
    "Youden", "MaxEfficiency", "Minimax", "MaxDOR", "MaxKappa", "MinValueNPV",
    "MinValuePPV", "ValueNPV", "ValuePPV", "MinValueNPVPPV", "PROC01", "NPVEqualPPV",
    "MaxNPVPPV", "MaxSumNPVPPV", "MaxProdNPVPPV", "ValueDLR.Negative",
    "ValueDLR.Positive", "MinPvalue", "ObservedPrev", "MeanPrev", "PrevalenceMatching"),
  show.plot = TRUE,
  show.result = FALSE
)

Arguments

markers

A numeric data frame or matrix with exactly two columns. Each column should contain one diagnostic marker.

status

A factor or vector indicating the true disease status. It must contain exactly two non-missing classes, and both classes must be represented in the data.

event

A single non-missing value indicating which level of status should be treated as the positive/event class.

method

A character string specifying the model or combination method. This argument is returned unchanged; method-specific validation should be handled by the calling function.

direction

A character string specifying the ROC direction. Possible values are "<" and ">".

conf.level

A numeric value between 0 and 1 specifying the confidence level used for ROC-related summaries.

cutoff.method

A character string specifying the cutoff selection method used for ROC analysis.

show.plot

A logical value indicating whether the ROC plot should be displayed.

show.result

A logical value indicating whether results should be printed to the console.

Value

A list containing the validated and prepared values: markers, status, event, method, direction, conf.level, cutoff.method, show.plot, and show.result.