Package {pye}

Integer. Number of folds for cross-validation.

Data frame. Input dataset containing predictors and target.

Character vector or data frame. Names of predictor variables. Defaults to all columns not in 'y' or 'C'.

Character or data frame. Name of the binary target variable (0/1). Defaults to '"y"'.

Character vector or data frame. Names of covariate variables for 'covYI'. Default is 'NULL'.

Numeric in (0, 1]. Elastic-net mixing parameter for AucPR. '1' = Lasso, '(0, 1)' = Elastic-Net.

Numeric vector. Penalization parameter(s) for predictors 'X'.

Numeric vector. Penalization parameter(s) for covariates 'C' in 'covYI'. Ignored if 'c_function_of_covariates = FALSE'.

A 'numeric' value between 0 and 1 specifying the weight for the Weighted Youden Index in covYI. Sensitivity is weighted by 'w_g' and specificity by '1 - w_g'. Default is 0.5 (which corresponds to the standard Youden Index).

character or numeric value specifying the classification cut-point used to convert continuous predictions into binary outcomes. If set to ‘"Youden"', the function computes the optimal cut-point using Youden’s Index. If a numeric value is provided, it is used directly as the threshold. Default is "Youden".

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is 'NULL'.

Integer (0, 1, 2). Level of printed output.

Integer. Random seed for reproducibility.

Integer. Number of CPU cores for parallelization.

Logical. If 'TRUE', scale predictors and covariates.

Logical. If 'TRUE', estimate cut-off as a function of covariates via 'covYI'.

Logical. If 'TRUE', estimate betas and gammas jointly.

Character. Metric to select 'lambda' when 'simultaneous = FALSE'. One of '"auc"', '"aauc"', '"aYI"', '"yi"', '"sen"', '"spc"', '"gm"', '"fdr"', '"mcc"', '"ccr"'.

Numeric. Elastic-net mixing parameter for 'covYI'.

Character. Penalty type for 'covYI': '"L12"', '"L1"', '"EN"', '"SCAD"', '"MCP"'.

Character. Kernel type for density estimation in 'covYI'.

Numeric. Parameters for SCAD/MCP penalties in 'covYI'.

Character. '"monotone"' uses mmAPG, '"nonmonotone"' uses mnmAPG.

Numeric vector. Starting point for gammas.

Character. '"zeros"' or '"corr"'.

Numeric vector. True gamma coefficients (optional).

Integer. Max iterations for 'covYI' optimization.

Numeric. Optimization parameters for 'covYI'.

Logical. If 'FALSE', skip aAUC/aYI computation.

Character. Path to a file for logging output from parallel workers. If 'NULL', output goes to the console. Default is '"log_AUC_models.txt"'.

The type of model used (e.g., "AucPR_EN").

The alpha value used for the AucPR model.

The penalty type used for the 'covYI' model.

The total time taken for the cross-validation, in minutes

A series of nested lists, each containing performance matrices for the respective measure of the first-step estimated method.

A series of nested lists, each containing performance matrices for the respective measure of the final estimated method.

A matrix showing the number of non-zero beta coefficients for each fold and lambda value.

A list of matrices showing the number of non-zero gamma coefficients for each fold, lambda, and tau value.

A list of the estimated beta coefficients for each fold.

A list of the omptimal estimated beta coefficients used for the estimation of the gammas, for each fold.

A list of the estimated gamma coefficients for each fold.

A vector containing the optimal lambda value selected by each performance measure.

A vector containing the optimal tau value selected by each performance measure (only if 'c_function_of_covariates' is TRUE).

A data frame containing the complete dataset.

A character vector of column names from 'df' to be used as regressor variables. Alternatively, a data frame containing only the regressors. If not specified, all columns not in 'y' are used.

A character string specifying the column name of the target variable in 'df'. It must be a binomial variable with values 0 or 1. Alternatively, a data frame containing only the target variable. Default is "y".

A single numeric value for the regularization parameter. A larger value results in stronger penalization.

The elastic-net mixing parameter. A value of 1 corresponds to L1 penalization (Lasso), while a value between 0 and 1 corresponds to Elastic-Net. Default is 1.

character or numeric value specifying the classification cut-point used to convert continuous predictions into binary outcomes. If set to ‘"Youden"', the function computes the optimal cut-point using Youden’s Index. If a numeric value is provided, it is used directly as the threshold. Default is "Youden".

numeric. An optional fold number, used when the function is called within a cross-validation loop. This is primarily for tracking and reporting purposes. Default is 'NULL'.

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is 'NULL'.

An integer controlling the amount of output. '0' for no output, '1' for a summary of the results, and '2' for a detailed breakdown of all steps. Default is 1.

The number of elements to show when printing results. Default is 10.

Additional arguments passed to methods

A character string indicating the final model type used, either "AucPR_L1" or "AucPR_EN".

The estimated vector of optimal beta coefficients.

A character vector containing the names of all regressor variables (X) used in the model estimation. This vector defines the canonical order of the regressors used to align the coefficients in betas_hat.

The Youden Index value at the optimal cut-point, which is a measure of the overall effectiveness of a diagnostic test.

The sensitivity (True Positive Rate) at the optimal cut-point.

The specificity (True Negative Rate) at the optimal cut-point.

The geometric mean of sensitivity and specificity.

The False Discovery Rate at the optimal cut-point.

The Matthews Correlation Coefficient, a measure of the quality of binary classification.

The overall correct classification rate.

The Area Under the ROC Curve (AUC).

The penalization parameter used in the estimation.

The alpha parameter used in the estimation.

The optimal cut-point for the 'z_hat' score.

A data frame with the estimated linear combination of regressors for each observation.

A data frame with the predicted binary outcomes (0 or 1) for each observation.

The number of non-zero beta coefficients estimated.

The total number of regressors considered.

The number of estimated betas that are zero.

The number of estimated betas that are non-zero.

The number of true non-zero betas correctly identified as non-zero (if 'regressors_betas' is provided).

The number of true non-zero betas incorrectly identified as zero.

The number of true zero betas correctly identified as zero.

The number of true zero betas incorrectly identified as non-zero.

The time taken for the estimation, in minutes.

A data frame containing the new dataset for prediction.

A character string specifying the column name of the target variable in 'df'. It must be a binomial variable with values 0 or 1. Default is "y".

A list containing the parameters from a model trained by the 'AucPR_estimation' function, specifically the 'betas_hat' and 'c_hat' components.

numeric. An optional fold number, used when the function is called within a cross-validation loop. This is primarily for tracking and reporting purposes. Default is 'NULL'.

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is 'NULL'.

An integer controlling the amount of output. '0' for no output, '1' for a summary of the results, and '2' for a detailed breakdown of all steps. Default is 1.

The number of elements to show when printing results. Default is 10.

A logical flag to suppress printing of results. If 'TRUE', the function will not print the summary to the console, as the output is expected to be handled by an external function (e.g., 'covYI'). Default is 'FALSE'.

Additional arguments passed to methods

The model type ("AucPR_L1" or "AucPR_EN").

The estimated vector of optimal beta coefficients.

The Youden Index value at the optimal cut-point.

The sensitivity at the optimal cut-point.

The specificity at the optimal cut-point.

The geometric mean of sensitivity and specificity.

The False Discovery Rate at the optimal cut-point.

The Matthews Correlation Coefficient.

The overall correct classification rate.

The Area Under the ROC Curve (AUC).

The penalization parameter used in the estimation.

The alpha parameter used in the estimation.

The optimal cut-point for the 'z_hat' score.

A data frame with the estimated linear combination of regressors for each observation.

A data frame with the predicted binary outcomes (0 or 1).

The total number of regressors considered.

The number of estimated betas that are zero.

The number of estimated betas that are non-zero.

The number of true non-zero betas correctly identified as non-zero (if 'regressors_betas' is provided).

The number of true non-zero betas incorrectly identified as zero.

The number of true zero betas correctly identified as zero.

The number of true zero betas incorrectly identified as non-zero.

The counts from the confusion matrix.

The time taken for the prediction.

numeric vector. The vector of coefficients (e.g., \beta) on which to apply the MCP penalization.

numeric. The penalty parameter (\lambda > 0).

numeric. The hyperparameter of the MCP penalization (a > 1). This controls the concavity and asymptote of the penalty.

numeric vector. The vector of coefficients (e.g., \beta) on which to apply the SCAD penalization.

numeric. The penalty parameter (\lambda > 0).

numeric. The hyperparameter of the SCAD penalization (a > 2). This parameter controls the clipping point and the rate at which the penalty tapers off. Common values include a=3.7.

Function that needs to be cross-validated. It needs to have a have just one parameter to change (theoretically called lambda), changing which the number of selected variables might change.

Name of the variable (a vector) to check if, reducing lambda, the number of its elements increases.

Starting value of lambda. If left big might take longer (default is 5)

floor value for lambda (default is 1e-20)

Minimum number of variables at which the process stops

Number to multiply or divide the considered lambda in the step. The higher, the slower to find the optimal value. Default is 2.

Function that needs to be cross-validated. It needs to have a have just one parameter to change (theoretically called lambda), changing which the number of selected variables might change.

Name of the variable (a vector) to check if, reducing lambda, the number of its elements increases.

Starting value of lambda. If left too small it might take longer (default is 0.0001)

floor value for lambda (default is 1e-20)

Maximum number of variable to accept the result of the function (default is 100.000)

Number to multiply or divide the considered lambda in the step. The higher, the slower to find the optimal value. Default is 2.

A data frame containing the input data, including the latent variable/score ('z'), the binary target variable ('y'), and covariates ('C').

Character string. The column name in 'df' representing the latent variable or score (e.g., from a primary prediction model). Default is "z_hat".

Character string. The column name in 'df' representing the binary target variable (0 or 1). Default is "y".

Character vector. Column names from 'df' to be used as covariate variables for the cut-point 'c'. This vector must include "const" if an intercept is desired for the covariate combination.

Numeric vector. The coefficients of the covariates ('C') used to evaluate the cut-point 'c'. The first element of this vector is assumed to correspond to the constant (intercept) term if "const" is in 'C'.

Numeric. The penalization parameter for the covariates 'C' in the 'covYI' calculation. Default is 0, indicating no penalization. Must be a single non-negative value.

A 'numeric' value between 0 and 1 specifying the weight for the Weighted Youden Index. Sensitivity is weighted by 'w' and specificity by '1 - w'. Default is 0.5 (which corresponds to the standard Youden Index).

Character string. The kernel type to use for the estimation of the density function in the Kernel Smooth method. Supported options include "gaussian", "normal", "uniform", "rectangular", "triangular", "epanechnikov", "biweight", "triweight", "tricube", "parzen", "cosine", and "optcosine". Default is "gaussian".

Numeric. A value between 0 and 1, representing the elastic-net mixing parameter for the EN penalization term. Default is 0.5.

Numeric. The 'a' parameter for the SCAD penalization term. Default is 3.7.

Numeric. The 'a' parameter for the MCP penalization term. Default is 3.0.

Character string. The type of penalization to apply. Must be one of "L12", "L1", "EN", "SCAD", or "MCP". Default is "L1".

Numeric. The exponent used in the bandwidth calculation for the Kernel Smooth density estimation. Default is 0.2.

Logical. If 'TRUE', the Youden Index (YI) returned is the empirical maximum Youden Index derived from 'OptimalCutpoints' for the given ‘z' and 'y'. If 'FALSE', it’s the 'yi' calculated from 'f0 - f1'. Default is 'FALSE'.

Logical. If 'FALSE', the covariate-adjusted AUC (aAUC) and adjusted Youden Index (aYI) are not computed, which can save computation time if these measures are not required. Default is 'FALSE'.

Numeric. The Penalized Youden Index (pye) using the L1 / 2 penalty.

Numeric. The Penalized Youden Index (pye) using the L1 penalty.

Numeric. The Penalized Youden Index (pye) using the Elastic-Net penalty.

Numeric. The Penalized Youden Index (pye) using the SCAD penalty.

Numeric. The Penalized Youden Index (pye) using the MCP penalty.

Numeric vector. The gradient of the Youden Index ('yi') with respect to the 'gammas' coefficients (excluding the constant term).

Numeric. The unpenalized Youden Index calculated using the Kernel Smooth density estimator (or the empirical Youden Index if prediction = TRUE). It is weighted if w is not 0.5.

Numeric. The sensitivity (True Positive Rate) of the classification.

Numeric. The specificity (True Negative Rate) of the classification.

Numeric. The geometric mean of sensitivity and specificity.

Numeric. The False Discovery Rate.

Numeric. The Matthews Correlation Coefficient.

Numeric. The Area Under the ROC Curve (AUC) from 'OptimalCutpoints'.

Numeric. The covariate-adjusted Area Under the ROC Curve (aAUC). This is 0 if 'run_aauc' is 'FALSE' or if computation fails.

Numeric. The adjusted Youden Index (aYI). This is 0 if 'run_aauc' is 'FALSE' or if computation fails.

Numeric. The overall correct classification rate.

Data frame. A data frame with 'ID' and the 'z' values used in the calculation.

Data frame. A data frame with 'ID' and the estimated cut-point values ('c_hat') for each observation.

Data frame. A data frame with 'ID' and the predicted binary outcomes ('y_hat').

Numeric. Number of True Positives.

Numeric. Number of True Negatives.

Numeric. Number of False Positives.

Numeric. Number of False Negatives.

List. A list containing the input parameters used for this function call: 'gammas', 'tau', 'w', 'alpha', 'a1', 'a2', and 'kernel'.

The input dataset as a data frame.

A single regressor or a known combination of regressors. It should be a character string specifying the column name in 'df'. Default is "z_hat".

The target variable, which must be a binomial (0 or 1) variable. It should be a character string specifying the column name in 'df'. Default is "y".

A character vector of column names from 'df' to be used as covariate variables. It is mandatory and cannot be 'NULL' or empty.

The penalization parameter applied to the covariates. Default is 0, which corresponds to no penalization.

A 'numeric' value between 0 and 1 specifying the weight for the Weighted Youden Index. Sensitivity is weighted by 'w' and specificity by '1 - w'. Default is 0.5.

The type of penalization to apply. Must be one of "L12", "L1", "EN", "SCAD", or "MCP". Default is "L1".

A numeric vector of specific starting points for the 'gammas' coefficients. Default is 'NULL'.

A character string to set the default starting point for 'gammas'. If "zeros", it starts with all zero values. If "corr", it starts with the correlation of each regressor with the target variable. Default is "zeros".

The elastic-net mixing parameter, for use with the "EN" penalty. A value between 0 and 1. Default is 0.5.

The 'a' parameter for the SCAD penalization term. Default is 3.7.

The 'a' parameter for the MCP penalization term. Default is 3.0.

A vector containing the true gamma coefficients (if known). Used for diagnostic purposes. Default is 'NULL'.

numeric. An optional fold number, used when the function is called within a cross-validation loop. This is primarily for tracking and reporting purposes. Default is 'NULL'.

The maximum number of iterations for the optimization algorithms. Default is 10000.

The number of elements to show when printing results. Default is 10.

A character string specifying the optimization algorithm to use. If "monotone", the mmAPG algorithm is used. If "nonmonotone", mnmAPG is used. Default is "monotone".

The parameter for the convergence condition of the optimization algorithm. Default is 1e-5.

The maximum value of the step-size parameter alpha. Default is 10000.

The parameter to adjust the step-size in the backtracking line search. Taking values between 0 and 1, the closer to 1, the more accurate the estimation will be. Default is 0.8.

The minimum value of the step-size parameter alpha. Default is 1e-10.

The error tolerance for considering the algorithm to have converged. Default is 1e-7.

An integer controlling the level of output. 2: visualize all steps, 1: visualize just the final result, 0: visualize nothing. Default is 1.

An integer to fix the random seed. Default is 1.

The kernel type to use for the estimation of the density function. Currently only "gaussian" is fully supported. Default is "gaussian".

A logical value. If 'FALSE', the aAUC and aYI metrics are not computed to save estimation time. Default is 'FALSE'.

The vector of optimal gamma coefficients found by the algorithm.

The final maximum penalized Youden Index (pye) value.

The gradient of the Youden Index with respect to the gammas at the optimal solution.

The input penalization parameter.

The type of penalty used.

The starting point for the gamma coefficients.

The kernel type used.

A data frame with the estimated cut-point for each observation.

A data frame with the regressor values used in the calculation.

A data frame with the predicted binary outcomes.

The Youden Index value at the optimal solution.

The sensitivity (True Positive Rate) at the optimal cut-point.

The specificity (True Negative Rate) at the optimal cut-point.

The geometric mean of sensitivity and specificity.

The False Discovery Rate.

The Matthews Correlation Coefficient.

The Area Under the ROC Curve (AUC).

The covariate-adjusted AUC (aAUC). Only computed if 'run_aauc' is 'TRUE'.

The adjusted Youden Index (aYI). Only computed if 'run_aauc' is 'TRUE'.

The overall correct classification rate.

Number of True Positives.

Number of True Negatives.

Number of False Positives.

Number of False Negatives.

The number of non-zero gamma coefficients in the final estimation.

The total number of gamma coefficients estimated.

The number of estimated gammas that are zero.

The number of estimated gammas that are non-zero.

Number of true non-zero gammas correctly identified as non-zero (if 'regressors_gammas' is provided).

Number of true non-zero gammas incorrectly identified as zero.

Number of true zero gammas correctly identified as zero.

Number of true zero gammas incorrectly identified as non-zero.

character vector. A list containing the input parameters.

The time taken for the estimation, in minutes.

The number of iterations performed by the optimization algorithm.

integer. Number of observations (rows) to generate.

integer. Number of regressor variables. Must be a multiple of 4 (required by subsequent sampling functions).

integer. Number of covariate variables. Must be a multiple of 4.

numeric. Maximum absolute correlation allowed among all generated variables. Actual correlations are randomly drawn from a normal distribution centered at 0, with a standard deviation scaled by max_corr. Must be strictly between 0 and 1.

numeric vector. Mean values for regressor variables. Its length must match cols_reg. Defaults to a zero vector.

numeric vector. Mean values for covariate variables. Its length must match cols_cov. Defaults to a zero vector.

integer. Number of latent factors used in the covariance matrix construction. Default is 2. Higher values can lead to more complex correlation structures.

integer. Seed for reproducibility. Default is 1.

Data frame of standardized normal regressors (mean 0, variance 1).

Data frame of standardized normal covariates (mean 0, variance 1).

integer. The number of \lambda values to generate in the sequence. Must be \ge 2.

numeric. The maximum (starting) value for \lambda. This is usually a value near where all coefficients are zero. Must be $> lmin$.

numeric. The minimum (ending) value for \lambda. This is usually a small positive number to ensure model sparsity. Must be \ge 0.

numeric. Number of rows for the training sample. Default is 50.

numeric. Total number of regressor variables in both training and test samples. Must be a multiple of 4. Default is 2000.

numeric. The correlation coefficient used to define the internal correlation within each of the four block-diagonal structures for generating regressors. Higher values result in more correlated features. Must be between -1 and 1. Default is 0.5.

numeric vector. Mean vector for the multivariate normal distribution used to generate the regressors. Its length must match cols. Default is a vector of zeros of length cols.

numeric. Number of rows for the test sample. Default is 1000. It is recommended to create a test sample larger than the training sample.

numeric. An integer to fix the random seed for reproducibility. Default is 1.

numeric vector or NULL. A vector of two distinct integers specifying the column indices of the "real regressors" (used in the latent variable z) from the first cols/4 block. If NULL, two are randomly selected. Indices are relative to the full set of cols variables.

numeric vector or NULL. Indices of "real regressors" from the second cols/4 block.

numeric vector or NULL. Indices of "real regressors" from the third cols/4 block.

numeric vector or NULL. Indices of "real regressors" from the fourth cols/4 block.

A data frame with the generated target variable (y) and all regressors, before scaling.

A list containing the full dataset, with regressors scaled (mean 0, variance 1) and the target y unscaled.

The data frame for the training set, with scaled regressors and unscaled target.

The data frame for the test set, with scaled regressors and unscaled target.

A numeric vector indicating the cols column indices of the 8 selected "real regressors".

A character vector of the names of the 8 selected "real regressors".

A numeric vector of the fixed coefficients used for the "real regressors" in the linear combination to generate z (fixed as c(-16, -4, 12, 8, -8, -12, 4, 16)).

A character string representing the linear formula used to generate the latent variable z.

A numeric vector of the latent linear predictor values for all observations.

A numeric value, the \mathbf{0.7} quantile of z, used as the threshold to binarize y.

integer. Number of observations for the training sample. Default is 50.

integer. Total number of regressor variables (biomarkers). Must be a multiple of 4. Default is 2000.

integer. Total number of covariate variables. Must be a multiple of 4. Default is 20. Increase this for high- dimensional covariate settings.

numeric. The maximum correlation coefficient used in the latent factor model for generating variables. Higher values lead to more correlated features. Must be between 0 and 1. Default is 0.3.

numeric vector. Mean vector for the multivariate normal distribution used to generate the regressors. Its length must match cols. Default is a vector of zeros.

numeric vector. Mean vector for the multivariate normal distribution used to generate the covariates. Its length must match cols_cov. Default is a vector of zeros.

integer. Number of observations for the test sample. Default is 1000.

integer. An integer to fix the random seed for reproducibility. Default is 1.

numeric vector or NULL. Indices of the two "real regressors" chosen from the first cols/4 block of variables. If NULL, two are randomly selected.

numeric vector or NULL. Indices of the two "real regressors" chosen from the second cols/4 block of variables. If NULL, two are randomly selected.

numeric vector or NULL. Indices of the two "real regressors" chosen from the third cols/4 block of variables. If NULL, two are randomly selected.

numeric vector or NULL. Indices of the two "real regressors" chosen from the fourth cols/4 block of variables. If NULL, two are randomly selected.

numeric or NULL. Index of the single "real covariate" chosen from the first cols_cov/4 block. If NULL, one is randomly selected.

numeric or NULL. Index of the single "real covariate" chosen from the second cols_cov/4 block. If NULL, one is randomly selected.

numeric or NULL. Index of the single "real covariate" chosen from the third cols_cov/4 block. If NULL, one is randomly selected.

numeric or NULL. Index of the single "real covariate" chosen from the fourth cols_cov/4 block. If NULL, one is randomly selected.

integer. Number of latent factors used in the covariance matrix construction. Default is 2. Higher values create more complex correlation structures.

A data frame of the full sample (rows = rows_train + rows_test) containing the generated target variable (y), all standardized regressors (X), and all standardized covariates (C).

The training subset of df.

The test subset of df.

numeric vector of the column indices of the selected "real regressors" from the full cols set.

character vector of the names of the selected "real regressors."

numeric vector of the coefficients used for the "real regressors" in the latent variable z.

numeric vector of the column indices of the selected "real covariates" from the full cols_cov set.

character vector of the names of the selected "real covariates."

numeric vector of the coefficients used for the "real covariates" in the dynamic cutoff.

The name of the target variable (always "y").

Character string of the formula used to generate the latent predictor z.

Character string of the formula used to generate the dynamic cutoff.

character vector of all regressor variable names.

character string, the name of the target variable.

character vector of all covariate variable names.

numeric vector of the latent linear predictor values for all observations.

numeric vector of the dynamic cutoff values for all observations.

A named numeric vector representing the starting point for the optimization. It is highly recommended to use the zero vector to encourage a sparse solution.

The index position of the constant term (intercept) in the x0 vector. Use NULL if no constant is included. Default is NULL.

A function that computes the gradient of the smooth (loss) component, f(x), of the objective function.

A function that computes the proximal operator related to the non-smooth (penalty) component, g(x).

A function that computes the full objective function, F(x) = f(x) + g(x).

The penalization parameter (\lambda) related to g(x). Used primarily for tracing and reporting. Default is NULL.

The type of penalty (e.g., "L1", "SCAD"). Used for tracing and reporting. Default is NULL.

An optional numeric fold number, typically used when the function is called within a cross-validation loop. Default is NULL.

The shrinking factor for the step-size \alpha in the backtracking line search. Must be in $(0, 1)$. A value closer to 1 increases accuracy but slows convergence. Default is 0.8.

The maximum value allowed for the step-size \alpha. Default is 10000.

The minimum value allowed for the step-size \alpha. If \alpha_x + \alpha_y falls below this threshold, the algorithm is considered converged. Default is 1e-10.

The convergence criterion parameter used in the line-search condition: F(z_k) \le F(y_k) - \delta \|z_k - y_k\|_2^2. Default is 1e-5.

An integer to control output verbosity: 2 = print details for every step; 1 = print only final result and convergence message; 0 = no output. Default is 2.

Numeric seed for reproducibility. Default is 1.

The maximum number of iterations. Default is 10000.

The absolute tolerance used for the 'minimum change' convergence criterion: convergence is assumed if the objective function changes by less than this value for 5 consecutive iterations. Default is 1e-7.

The iteration number after which any coefficient that becomes zero is permanently fixed to zero. This enforces sparsity. Default is 20.

The number of non-zero elements to display in the trace output. Default is 10.

The final estimated vector of parameters, including the constant.

The total number of main algorithm iterations performed.

The total number of backtracking steps executed.

The total time taken for the estimation (in minutes).

The convergence reason ("max_iter", "min_change", or "min_alpha").

A named numeric vector representing the starting point for the optimization. It is highly recommended to use the zero vector to encourage a sparse solution.

The index position of the constant term (intercept) in the x0 vector. Use NULL if no constant is included. Default is NULL.

A function that computes the gradient of the smooth (loss) component, f(x), of the objective function.

A function that computes the proximal operator related to the non-smooth (penalty) component, g(x).

A function that computes the full objective function, F(x) = f(x) + g(x).

The penalization parameter (\lambda) related to g(x). Used primarily for tracing and reporting. Default is NULL.

The type of penalty (e.g., "L1", "SCAD"). Used for tracing and reporting. Default is NULL.

An optional numeric fold number, typically used when the function is called within a cross-validation loop. Default is NULL.

The shrinking factor for the step-size \alpha in the backtracking line search. Must be in $(0, 1)$. A value closer to 1 increases accuracy but slows convergence. Default is 0.8.

The non-monotonicity control parameter \eta \in [0, 1]. It dictates how much the current objective function value can deviate from the best previous value. Li and Lin (2015) suggest $0.8$. Default is 0.8.

The maximum value allowed for the step-size \alpha. Default is 10000.

The minimum value allowed for the step-size \alpha. If \alpha_x + \alpha_y falls below this threshold, the algorithm is considered converged. Default is 1e-10.

The convergence criterion parameter used in the line-search condition (see mmAPG). Default is 1e-5.

An integer to control output verbosity: 2 = print details for every step; 1 = print only final result and convergence message; 0 = no output. Default is 2.

Numeric seed for reproducibility. Default is 1.

The maximum number of iterations. Default is 10000.

The absolute tolerance used for the 'minimum change' convergence criterion: convergence is assumed if the objective function changes by less than this value for 5 consecutive iterations. Default is 1e-7.

The iteration number after which any coefficient that becomes zero is permanently fixed to zero. This enforces sparsity. Default is 5.

The number of non-zero elements to display in the trace output. Default is 10.

The final estimated vector of parameters, including the constant.

The total number of main algorithm iterations performed.

The total number of backtracking steps executed.

The total time taken for the estimation (in minutes).

The convergence reason ("max_iter", "min_change", or "min_alpha").

Integer. The number of simulation experiments to run. Default is 1000.

A data frame containing the complete dataset, including the target variable, regressors, and optional covariates.

Character vector. Column names from 'df' to be used as regressors in the model estimation. It can be a data frame (whose column names will be extracted) or a character vector. Defaults to all columns in 'df' not specified as 'y' or 'C'.

Character string. The column name in 'df' representing the binary target variable (0 or 1). It can be a data frame (whose first column name will be extracted) or a character string. Default is "y".

Character vector or 'NULL'. Column names from 'df' to be used as covariate variables in covYI. It can be a data frame or a character vector. Default is 'NULL'.

Function. The function to use for model estimation. Expected values are "plr_estimation", "psvm_estimation", "AucPR_estimation".

Function. The function to use for model prediction. Expected values are "plr_predict", "psvm_predict", "AucPR_predict".

Character string. The specific model to use in the estimation. Examples include "logLasso", "logElasticNet", "logSCAD", "logMCP", "SCADSVM", "ElasticSCADSVM", "l1SVM", "enSVM", "AucPR_L1", "AucPR_EN".

Numeric. The penalization parameter for the regressors 'X'. Must be a single non-negative value.

Numeric. The penalization parameter for the covariates 'C' in covYI. Default is 0, indicating no penalization. Must be a single non-negative value.

Numeric. A value between 0 and 1 specifying the weight for the Weighted Youden Index in covYI. Sensitivity is weighted by 'w_g' and specificity by '1 - w_g'. Default is 0.5 (which corresponds to the standard Youden Index).

Numeric. A numeric value between 0 and 1. The proportion of the total observations in 'df' to be used for the training set in each simulation split. The split is performed using stratified sampling on 'y' to maintain class balance. Default is 0.7 (70% training, 30% testing).

Integer (0, 1, or 2). Controls the verbosity of the output. 2 for all steps, 1 for main results, 0 for no output. Default is 1.

Numeric. A value between 0 and 1, the elastic-net mixing parameter for the primary model's penalty. Default is 0.5.

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is 'NULL'.

Integer. Number of CPU cores to use for parallel processing. If 0, it automatically uses 70% of available physical cores. If 1, no parallelization is adopted. Default is 1.

Logical. If 'TRUE', the dataset 'df' is scaled (mean 0, variance 1) before processing. Default is 'FALSE'.

Logical. If 'TRUE', 'covYI' is used to estimate the cut-off point as a function of the covariate information 'C'. If 'FALSE', the covariate information is ignored for the cutoff. Default is 'FALSE'.

Numeric. A value between 0 and 1, the elastic-net mixing parameter for the 'covYI' penalty. Default is 0.5.

Character string. The penalty type for 'covYI'. To be chosen among "L12", "L1", "EN", "SCAD", "MCP". Default is "L1".

Character string. The kernel type to use for the estimation of the density function in 'covYI'. (Note: tested primarily for "gaussian"). Default is "gaussian".

Numeric. The 'a' parameter for SCAD and MCP penalties in 'covYI'. Default is 3.7.

Numeric. The 'b' parameter for the MCP penalty in 'covYI'. Default is 3.0.

Character string. For 'covYI' optimization. If "monotone", mmAPG is used; if "nonmonotone", mnmAPG is used. Default is "monotone".

Numeric vector or 'NULL'. A specific starting point for gamma coefficients in 'covYI'. Default is 'NULL', meaning no custom starting point is provided.

Character string. Sets the default starting point of gamma coefficients if 'gamma_start_input' is 'NULL'. If "zeros", it starts with all zero values; if "corr", it starts with the correlation of every covariate with the target variable. Default is "zeros".

Numeric vector or 'NULL'. A vector containing the indices of the true non-zero gamma coefficients (if known), used for performance evaluation of variable selection. Default is 'NULL'.

Integer. Maximum number of iterations for the 'covYI' optimization algorithm (mmAPG and mnmAPG). Default is 10000.

Numeric. Parameter for the convergence condition of the 'covYI' optimization algorithm. Default is 1e-5.

Numeric. Maximum value of the step-size parameter alpha in ‘covYI'’s backtracking line-search. Default is 10000.

Numeric. Parameter to adjust the step-size in the backtracking line-search for 'covYI' optimization. Takes values between 0 and 1. Closer to 1 implies more accurate estimation but longer computation time. Default is 0.8.

Numeric. Minimum value of the step-size parameter alpha in ‘covYI'’s backtracking line-search. Default is 1e-12.

Numeric. The error threshold to accept for considering the 'covYI' algorithm converged. Default is 1e-7.

Logical. If 'FALSE', the aAUC and aYI measures are not computed, which can save estimation time if not requested. Default is 'FALSE'.

Character. Path to a file for logging output from parallel workers. If 'NULL', output goes to the console. Default is "log_sim_Other_real.txt".

Character string. The type of model used for estimation.

Numeric. Total time taken for the entire simulation study in minutes.

Numeric. Mean estimation time for the primary model across all simulations.

Numeric. Mean estimation time for the covYI method across all simulations (0 if 'c_function_of_covariates' is 'FALSE').

Integer. The number of CPU cores used for parallelization.

Integer. The number of simulation experiments performed.

Numeric. The penalization parameter for the primary model.

Numeric. The penalization parameter for the covYI method.

Matrix (n x 2). AUC values for training and testing sets across all simulations for the primary model.

Matrix (n x 2). Youden's Index values for training and testing sets across all simulations for the primary model.

Matrix (n x 2). Sensitivity values for training and testing sets across all simulations for the primary model.

Matrix (n x 2). Specificity values for training and testing sets across all simulations for the primary model.

Matrix (n x 2). Geometric Mean values for training and testing sets across all simulations for the primary model.

Matrix (n x 2). False Discovery Rate values for training and testing sets across all simulations for the primary model.

Matrix (n x 2). Matthews Correlation Coefficient values for training and testing sets across all simulations for the primary model.

Matrix (n x 2). Correct Classification Rate values for training and testing sets across all simulations for the primary model.

Matrices (n x 2). Classification measures (AUC, aAUC, aYI, Youden's Index, Sensitivity, Specificity, Geometric Mean, FDR, MCC, Correct Classification Rate) for training and testing sets across all simulations for the covYI method (only if 'c_function_of_covariates' is 'TRUE').

Matrix (n x 1). Total number of regressors for betas in each simulation.

Matrix (n x 1). Number of predicted zero beta coefficients in each simulation.

Matrix (n x 1). Number of predicted non-zero beta coefficients in each simulation.

Matrix (n x 1). Number of true non-zero beta coefficients correctly identified as non-zero in each simulation.

Matrix (n x 1). Number of true non-zero beta coefficients incorrectly identified as zero in each simulation.

Matrix (n x 1). Number of true zero beta coefficients correctly identified as zero in each simulation.

Matrix (n x 1). Number of true zero beta coefficients incorrectly identified as non-zero in each simulation.

Matrix (n x 1). Total number of covariates for gammas in each simulation (only if 'c_function_of_covariates' is 'TRUE').

Matrix (n x 1). Number of predicted zero gamma coefficients in each simulation (only if 'c_function_of_covariates' is 'TRUE').

Matrix (n x 1). Number of predicted non-zero gamma coefficients in each simulation (only if 'c_function_of_covariates' is 'TRUE').

Matrix (n x 1). Number of true non-zero gamma coefficients correctly identified as non-zero in each simulation (only if 'c_function_of_covariates' is 'TRUE').

Matrix (n x 1). Number of true non-zero gamma coefficients incorrectly identified as zero in each simulation (only if 'c_function_of_covariates' is 'TRUE').

Matrix (n x 1). Number of true zero gamma coefficients correctly identified as zero in each simulation (only if 'c_function_of_covariates' is 'TRUE').

Matrix (n x 1). Number of true zero gamma coefficients incorrectly identified as non-zero in each simulation (only if 'c_function_of_covariates' is 'TRUE').

Matrix (p x 1). For each regressor, the number of times its coefficient was estimated as non-zero across all simulations. 'p' is the number of regressors in 'X'.

Matrix (q x 1). For each covariate, the number of times its coefficient was estimated as non-zero across all simulations (only if 'c_function_of_covariates' is 'TRUE'). 'q' is the number of covariates in 'C'.

Numeric vector. The fixed specificity points used for extracting ROC curve sensitivity values.

List of numeric vectors. Sensitivity points for ROC curves on training data for each simulation, corresponding to 'roc_spec_points'.

List of numeric vectors. Sensitivity points for ROC curves on testing data for each simulation, corresponding to 'roc_spec_points'.

Numeric vector or 'NULL'. The input 'regressors_betas' parameter, indicating true non-zero beta indices.

Numeric vector or 'NULL'. The input 'regressors_gammas' parameter, indicating true non-zero gamma indices.

character vector. A list containing the input parameters.

Logical. The input 'c_function_of_covariates' parameter.

Logical. The input 'run_aauc' parameter.

List of numeric vectors. The estimated beta coefficients from each simulation run. Each element of the list is a named numeric vector of coefficients for that simulation.

List of numeric vectors. The estimated gamma coefficients from each simulation run (only if 'c_function_of_covariates' is 'TRUE'). Each element of the list is a named numeric vector of coefficients for that simulation, including the 'const' term.

Integer. The number of folds for cross-validation. Must be at least 2.

A 'data.frame' containing the complete dataset, including predictors, the target variable, and any covariates.

A character vector of column names from 'df' to be used as regressors (predictors). Defaults to all columns in 'df' that are not 'y' or 'C'.

A character string specifying the column name of the binary target variable (must be coded as 0 and 1). Default is '"y"'.

A character vector of column names from 'df' to be used as covariates for 'covYI'. Default is 'NULL'.

A numeric vector of one or more non-negative penalization parameters for the regressors 'X'.

A numeric vector of one or more non-negative penalization parameters for the covariates 'C'. Used only if 'c_function_of_covariates' is 'TRUE'. Default is 0.

A 'numeric' value between 0 and 1 specifying the weight for the Weighted Youden Index in covYI. Sensitivity is weighted by 'w_g' and specificity by '1 - w_g'. Default is 0.5 (which corresponds to the standard Youden Index).

character or numeric value specifying the classification cut-point used to convert continuous predictions into binary outcomes. If set to ‘"Youden"', the function computes the optimal cut-point using Youden’s Index. If a numeric value is provided, it is used directly as the threshold. Default is "Youden".

A numeric value between 0 and 1 for the Elastic-Net mixing parameter in 'glmnet'. 'alpha = 1' is the lasso (default), and 'alpha = 0' is ridge regression.

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is 'NULL'.

Integer (0, 1, or 2). Controls the verbosity of the output. '0' = no output, '1' = summary results (default), '2' = detailed step-by-step output.

A character string specifying the penalized logistic regression model to use. Must be one of: '"logLasso"', '"logElasticNet"', '"logSCAD"', or '"logMCP"'.

Integer. A random seed for ensuring reproducibility of the fold assignments. Default is 1.

Integer. The number of CPU cores to use for parallel processing of folds. If '1' (default), execution is sequential.

Logical. If 'TRUE', the predictor and covariate columns of 'df' are standardized before model fitting. Default is 'FALSE'.

Logical. If 'TRUE', the cut-off point is estimated as a function of covariates 'C' using the 'covYI' method. Default is 'FALSE'.

Logical. If 'c_function_of_covariates' is 'TRUE', this determines the tuning strategy. If 'TRUE', a grid search over 'lambda' and 'tau' is performed. If 'FALSE' (default), a sequential two-step search is performed.

Character. The performance metric used to select the optimal 'lambda' in the first step of a sequential search (when 'simultaneous = FALSE'). Must be one of '"auc"', '"aauc"', '"aYI"', '"yi"', '"sen"', '"spc"', '"gm"', '"fdr"', '"mcc"', or '"ccr"'. Default is '"ccr"' (correct classification rate).

Numeric. The Elastic-Net mixing parameter for the 'covYI' model. Default is 0.5.

Character. The penalty type for 'covYI'. Must be one of '"L12"', '"L1"', '"EN"', '"SCAD"', '"MCP"'. Default is '"L1"'.

Character. The kernel for density estimation in 'covYI'. Default is '"gaussian"'.

Numeric. Regularization parameters for SCAD and MCP penalties in 'covYI'. Defaults are 3.7 and 3.0, respectively.

Character. Optimization algorithm for 'covYI': '"monotone"' (mmAPG) or '"nonmonotone"' (mnmAPG). Default is '"monotone"'.

An optional numeric vector for the starting coefficients ('gammas') in 'covYI'.

Character. Default starting point for 'gammas' if 'gamma_start_input' is 'NULL'. '"zeros"' (default) or '"corr"'.

An optional numeric vector of true gamma coefficients for simulation/evaluation. Default is 'NULL'.

Integer. Maximum iterations for 'covYI' optimization. Default is 10000.

Numeric. Advanced optimization parameters for 'covYI'. See 'covYI_KS_estimation' for details.

Logical. If 'FALSE' (default), the adjusted-AUC (aAUC) and adjusted-YI (aYI) are not computed to save time.

Character. Path to a file for logging output from parallel workers. If 'NULL', output goes to the console. Default is '"log_logistic_models.txt"'.

The primary model type used (e.g., '"logLasso"').

The penalty type used for 'covYI' (if applicable).

Total time for the cross-validation process.

A series of nested lists, each containing performance matrices for the respective measure of the first-step estimated method.

A series of nested lists, each containing performance matrices for the respective measure of the final estimated method.

The optimal 'lambda' value selected based on maximizing each performance measure (e.g., 'lambda_hat_auc', 'lambda_hat_ccr').

The optimal 'tau' value for each measure, if 'c_function_of_covariates' was 'TRUE'.

Input parameters defining the CV strategy.

The optimal 'lambda' chosen in the first step of a sequential search. 'NA' otherwise.

A matrix ('n_folds' x 'length(lambda)') showing the number of non-zero beta coefficients.

Number of non-zero betas for 'lambda_star' in a sequential search.

A list of matrices showing the number of non-zero gamma coefficients for each 'lambda' and 'tau' combination.

A list of the estimated beta coefficients for each fold and 'lambda'.

A list of estimated beta coefficients for 'lambda_star' in a sequential search.

A list of the estimated gamma coefficients for each fold, 'lambda', and 'tau' combination.

A data frame containing the complete dataset.

A character vector of column names from df to be used as regressor variables. Alternatively, a data frame containing only the regressors. If not specified, all columns not in y are used.

A character string specifying the column name of the target variable in df. It must be a binomial variable with values 0 or 1. Alternatively, a data frame containing only the target variable. Default is "y".

The elastic-net mixing parameter. A value of 1 corresponds to L1 penalization (Lasso). A value between 0 and 1 is used for Elastic-Net. Note: This parameter is only used when model_type = "logElasticNet"; for logLasso, alpha is forced to 1, and for logSCAD/logMCP, it is ignored as they do not typically use an alpha mixing parameter. Default is 0.5.

A single non-negative numeric value for the regularization parameter. A larger value results in stronger penalization.

A character string specifying the penalized logistic model to use. Options are: "logLasso" (L1 penalty, via glmnet), "logElasticNet" (Elastic-Net penalty, via glmnet), "logSCAD" (SCAD penalty, via ncvreg_modified in pye), and "logMCP" (MCP penalty, via ncvreg_modified in pye). Default is "logLasso".

character or numeric value specifying the classification cut-point used to convert continuous predictions into binary outcomes. If set to ‘"Youden"', the function computes the optimal cut-point using Youden’s Index. If a numeric value is provided, it is used directly as the threshold. Default is "Youden".

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is 'NULL'.

numeric. An optional fold number, used when the function is called within a cross-validation loop. This is primarily for tracking and reporting purposes. Default is 'NULL'.

An integer controlling the amount of output printed to the console. 0 for no output, 1 for a result summary, and 2 for a detailed breakdown. Default is 1.

The number of elements to show when printing results. Default is 10.

The fitted model object (from glmnet or ncvreg_modified).

A character string indicating the model type used.

The estimated vector of optimal beta coefficients (excluding the intercept).

A character vector containing the names of all regressor variables (X) used in the model estimation. This vector defines the canonical order of the regressors used to align the coefficients in betas_hat.

The Youden Index value at the optimal cut-point.

The sensitivity (True Positive Rate) at the optimal cut-point.

The specificity (True Negative Rate) at the optimal cut-point (spec).

The geometric mean of sensitivity and specificity (gm).

The False Discovery Rate at the optimal cut-point.

The Matthews Correlation Coefficient.

The overall correct classification rate (CCR).

The Area Under the ROC Curve (AUC).

The penalization parameter used.

The optimal cut-point for the z_hat score.

A data frame with the estimated linear combination of regressors (or probability) for each observation.

A data frame with the predicted binary outcomes (0 or 1).

The number of non-zero beta coefficients estimated.

The total number of regressors considered.

The number of estimated betas that are zero.

The number of estimated betas that are non-zero.

The number of true non-zero betas correctly identified as non-zero (if regressors_betas is provided).

The number of true non-zero betas incorrectly identified as zero (False Negatives).

The number of true zero betas correctly identified as zero (True Negatives).

The number of true zero betas incorrectly identified as non-zero (False Positives).

The counts of True Positives, True Negatives, False Positives, and False Negatives at the optimal cut-point.

The time taken for the estimation, in minutes.

A data frame containing the new dataset for prediction.

A character string specifying the column name of the target variable in 'df'. It must be a binomial variable with values 0 or 1. Default is "y".

A list containing the parameters from a model trained by the 'plr_estimation' function, specifically the 'betas_hat', 'c_hat', and 'model' components.

numeric. An optional fold number, used when the function is called within a cross-validation loop. This is primarily for tracking and reporting purposes. Default is 'NULL'.

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is 'NULL'.

An integer controlling the amount of output. '0' for no output, '1' for a summary of the results, and '2' for a detailed breakdown of all steps. Default is 1.

A logical flag used internally to suppress printing of results if the output is handled by an external function (e.g., 'covYI'). Default is 'FALSE'.

The number of elements to show when printing results. Default is 10.

The trained model object (e.g., from 'glmnet' or 'ncvreg').

The model type ("logLasso", "logMCP", etc.).

The estimated vector of optimal beta coefficients.

The Youden Index value at the optimal cut-point.

The sensitivity at the optimal cut-point.

The specificity at the optimal cut-point.

The geometric mean of sensitivity and specificity.

The False Discovery Rate at the optimal cut-point.

The Matthews Correlation Coefficient.

The overall correct classification rate.

The Area Under the ROC Curve (AUC).

The penalization parameter used in the estimation.

The optimal cut-point for the 'z_hat' score.

A data frame with the estimated linear combination of regressors for each observation.

A data frame with the predicted binary outcomes (0 or 1).

The total number of regressors considered.

The number of estimated betas that are non-zero.

The counts from the confusion matrix.

The time taken for the prediction.

numeric vector to which the proximal operator should be applied.

numeric. The overall non-negative penalization parameter \lambda.

numeric. The mixing parameter \alpha \in [0, 1]. \alpha = 1 is pure \textrm{L}_{1} (Lasso); \alpha = 0 is pure \textrm{L}_2 (Ridge).

Additional arguments passed to methods

numeric vector to which the proximal operator should be applied.

numeric. The non-negative penalization parameter \lambda.

Additional arguments passed to methods

numeric vector to which the proximal operator should be applied.

numeric. The non-negative penalization parameter \lambda.

numeric. The exponent for the \textrm{L}_{1 / 2} penalty, typically q=0.5. Must be 0 < q < 1. Default is 0.5.

integer. Maximum number of iterations for the fixed-point optimization loop for x_{\text{bar}}. Default is 10000.

numeric. Tolerance for the convergence of the fixed-point optimization loop. Default is 1e-10.

Additional arguments passed to methods

numeric vector to which the proximal operator should be applied.

numeric. The non-negative penalization parameter \lambda.

numeric. The hyperparameter a > 1 for the MCP penalty. It controls the threshold after which the penalty is zero. $a=3.0$ is a common choice.

Additional arguments passed to methods

numeric vector to which the proximal operator should be applied.

numeric. The non-negative penalization parameter \lambda.

numeric. The hyperparameter a > 2 for the SCAD penalty. It controls the concavity of the penalty function. a=3.7 is a common choice.

Additional arguments passed to methods

Integer. The number of folds to use for cross-validation (must be >= 2).

Data frame. The input dataset containing the target variable, regressors, and covariates.

Character vector. Names of the regressor variables (features). Defaults to all columns in "df" that are not "y" or "C". Can also be a data frame containing only the regressors.

Character. Name of the binary target variable (outcome), coded as 0 and 1. Defaults to "y". Can also be a data frame containing only the target variable.

Character vector. Names of the covariate variables for covariate-adjusted cut-point estimation. Defaults to "NULL" (no covariates). Can also be a data frame containing only the covariates.

Numeric vector. The regularization parameter(s) for the regressors "X".

Numeric vector. The regularization parameter(s) for the covariates "C" in "covYI". If "c_function_of_covariates = TRUE", this parameter cannot be "NULL" or contain only zeros. Default is 0 (no penalization).

A 'numeric' value between 0 and 1 specifying the weight for the Weighted Youden Index in covYI. Sensitivity is weighted by 'w_g' and specificity by '1 - w_g'. Default is 0.5 (which corresponds to the standard Youden Index).

Character or numeric. Specifies the classification cut-point used to convert continuous predictions into binary outcomes. If set to "Youden", the function computes the optimal cut-point using Youden's Index. If a numeric value is provided, it is used directly as the threshold. If "NULL", a default is assigned based on "model_type": "SCADSVM" uses "0", "ElasticSCADSVM", "l1SVM" or "enSVM" use "Youden".

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is "NULL".

Integer. Level of verbosity: 0 = silent, 1 = brief summary, 2 = verbose. Default is 1.

numeric in (0, 1]. Elastic-net mixing parameter for sparseSVM (alpha = 1 corresponds to L1). Default is 0.5.

Character. The SVM model to use. Options: "SCADSVM", "ElasticSCADSVM", "l1SVM", "enSVM".

Integer. Random seed for reproducibility. Default is 1.

Integer. Number of cores to use for parallel processing. If 1, no parallelization is used. Default is 1.

Logical. If "TRUE", the dataset is scaled. Default is "FALSE".

Logical. If "TRUE", "covYI" is used to estimate the cut-off point as a function of the covariates. Default is "FALSE".

Logical. If "TRUE" (and "c_function_of_covariates = TRUE"), gammas are estimated simultaneously with betas. If "FALSE", gammas are estimated as a second step. Default is "FALSE".

Character. The performance measure used to select the best lambda when "simultaneous = FALSE". Options: "auc", "aauc", "aYI", "ccr", "yi", "gm", "fdr", "mcc", "sen", "spc". Default is "ccr" (correct classification rate).

Numeric. Elastic-Net mixing parameter for "covYI". Default is 0.5.

Character. The penalty of "covYI". Options: "L12", "L1", "EN", "SCAD", "MCP". Default is "L1".

Character. Kernel type for density estimation in "covYI". Default is "gaussian".

Numeric. Parameter for the SCAD and MCP penalties in "covYI". Default is 3.7.

Numeric. Parameter for the MCP penalty in "covYI". Default is 3.0.

Character. For "covYI", if "monotone", mmAPG is used; if "nonmonotone", mnmAPG is used. Default is "monotone".

Numeric vector. A specific starting point for gammas. Default is "NULL".

Character. Sets the default starting point of gamma. If "zeros", it starts with all zero values; if "corr", it starts with the value of the correlation of every regressor with the target variable.

Numeric vector. Optional vector containing the true gammas (if known).

Integer. Maximum number of iterations in the algorithms mmAPG and mnmAPG in "covYI". Default is 10000.

Numeric. Parameter for the convergence condition of the optimization algorithm of "covYI". Default is 1e-5.

Numeric. Maximum value of the step-parameter alpha in "covYI". Default is 100.

Numeric. Parameter to adjust the step-size in the backtracking line-search, in the optimization of "covYI". Taking values between 0 and 1, the closer to 1, the more accurate the estimation will be, the longer it will take and vice versa. Default is 0.8.

Numeric. Minimum value of the step-parameter alpha in "covYI". Default is 1e-12.

Numeric. Error to accept for considering the algorithm converged in "covYI". Default is 1e-7.

Logical. If "FALSE", the aAUC and aYI are not computed, to save estimation time if not requested. Default is "FALSE".

Character. Path to a file for logging output from parallel workers. If "NULL", output goes to the console. Defaults to "log_SVM_models.txt".

The SVM model type used.

The classification cut-point used.

The penalty type used for covYI.

The time taken for cross-validation.

A series of nested lists, each containing performance matrices for the respective measure of the first-step estimated method.

A series of nested lists, each containing performance matrices for the respective measure of the final estimated method.

The optimal lambda values selected based on different performance measures.

The optimal tau values selected based on different performance measures (if 'c_function_of_covariates = TRUE').

Indicates whether the cut-off point was estimated as a function of covariates.

Indicates whether betas and gammas were estimated simultaneously.

The measure used to select lambda.

The optimal lambda value when using a sequential search.

The number of non-zero beta coefficients.

The number of non-zero beta coefficients when using lambda_star.

The number of non-zero gamma coefficients.

The estimated beta coefficients when using lambda_star.

The estimated beta coefficients.

The estimated gamma coefficients.

data.frame containing the observations (rows) and variables (columns).

character vector with names of predictors in 'df'. If omitted the function will attempt to use all columns in 'df' except 'y'.

single character string with the name of the binary outcome column in 'df' (allowed codings: 0/1 or -1/1).

numeric. Primary regularization parameter used by penalized estimators (SCAD, ElasticSCAD, sparseSVM). If NULL, methods that require a penalty will return an error.

numeric. Secondary L2 penalty used by ElasticSCADSVM.

numeric in (0, 1]. Elastic-net mixing parameter for sparseSVM (alpha = 1 corresponds to L1). Default is 0.5.

character scalar selecting the estimation method. Allowed values include: "SCADSVM", "ElasticSCADSVM", "l1SVM", "enSVM".

character or numeric value specifying the classification cut-point used to convert continuous predictions into binary outcomes. If set to ‘"Youden"', the function computes the optimal cut-point using Youden’s Index. If a numeric value is provided, it is used directly as the threshold. If 'NULL', a default is assigned based on 'model_type': '"SCADSVM"' uses '0', '"ElasticSCADSVM"', '"l1SVM"' or '"enSVM"' use '"Youden"'.

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is 'NULL'.

numeric. An optional fold number, used when the function is called within a cross-validation loop. This is primarily for tracking and reporting purposes. Default is 'NULL'.

integer verbosity level: 0 = silent, 1 = brief summary, 2 = verbose.

integer used to set RNG where supported by the back-end routines.

The number of elements to show when printing results. Default is 10.

The fitted model object returned by the selected backend (e.g. penalizedSVM object, sparseSVM object).

Character string with the selected model type.

Numeric named vector with estimated predictor coefficients where recoverable (zeros if unavailable). Names follow 'X'.

Numeric cutpoint computed by Youden's criterion on the training decision scores.

Data.frame with columns 'ID' and 'z_hat' (decision score).

Data.frame with columns 'ID' and 'y_hat' (predicted labels at 'c_hat').

Numeric scalar performance summaries computed on the training data.

Confusion matrix cell counts at 'c_hat'.

Model and tuning parameters used.

Variable selection diagnostics.

Elapsed wall clock time (minutes).

data.frame. The input dataset containing observations (rows) and variables (columns) for prediction.

character. The name of the target variable column in 'df'. This column should contain binary outcomes (0 and 1). Default is "y".

list. A list containing the fitted model and related information, as returned by the 'psvm_estimation' function. This list must include elements named 'betas_hat', 'c_hat', 'X_model', and 'model_type'.

numeric. An optional fold number, used when the function is called within a cross-validation loop. This is primarily for tracking and reporting purposes. Default is 'NULL'.

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is 'NULL'.

integer. Controls the level of verbosity during the function's execution. - 0: No output is printed. - 1: A summary of the results is printed. - 2: Detailed information about the calculations is printed. Default is 1.

The number of elements to show when printing results. Default is 10.

logical. If 'TRUE', indicates that the cut-off point ('c_hat') should be estimated as a function of covariates (using a method like covYI). If 'FALSE', a single cut-off value is used for all predictions. This parameter primarily affects whether results are printed within this function or handled externally. Default is 'FALSE'.

The fitted model object used for prediction (same as in 'model_to_use').

Character string indicating the type of SVM model used (same as in 'model_to_use').

Numeric vector of estimated beta coefficients from the fitted model (same as in 'model_to_use').

Numeric. Youden's J statistic, calculated on the predicted values.

Numeric. Sensitivity (true positive rate) of the predictions.

Numeric. Specificity (true negative rate) of the predictions.

Numeric. Geometric mean of sensitivity and specificity.

Numeric. False discovery rate.

Numeric. Matthews correlation coefficient.

Numeric. Correct classification rate (accuracy).

Numeric. Area under the ROC curve.

Numeric. Value of lambda used in the model (same as in 'model_to_use').

Numeric. Value of lambda2 used in the model (same as in 'model_to_use').

Numeric. Value of alpha used in the model (same as in 'model_to_use').

Numeric. The cut-off value used to convert decision scores into binary predictions (same as in 'model_to_use').

Data.frame with columns "ID" and "z_hat" (decision scores).

Data.frame with columns "ID" and "y_hat" (predicted binary outcomes).

Integer. Total number of variables (regressors) in the model.

Integer. Number of regressors with estimated coefficients of zero.

Integer. Number of regressors with estimated coefficients different from zero.

Integer. If 'regressors_betas' is provided, the number of non-zero "true" betas that were also identified as non-zero in the model.

Integer. If 'regressors_betas' is provided, the number of non-zero "true" betas that were incorrectly estimated as zero in the model.

Integer. If 'regressors_betas' is provided, the number of zero "true" betas that were also estimated as zero in the model.

Integer. If 'regressors_betas' is provided, the number of zero "true" betas that were incorrectly estimated as non-zero in the model.

Integer. Number of true positives.

Integer. Number of true negatives.

Integer. Number of false positives.

Integer. Number of false negatives.

difftime. The time elapsed during the prediction process.

A 'data.frame' containing the input dataset. Must include the columns specified in 'X' and 'y'.

A 'character' vector specifying the names of the regressor variables (biomarkers) to consider for the pye evaluation. Alternatively, a 'data.frame' containing only these regressors can be provided, in which case their column names will be used. Default is all columns in 'df' not specified as 'y'.

A 'character' string specifying the name of the target binary variable (outcome). This variable must contain only values 0 and 1. Alternatively, a single-column 'data.frame' containing only the target variable can be provided, in which case its column name will be used. Default is "y".

A 'numeric' vector representing the coefficients of the biomarker combination (Z = X %*% betas) used for the evaluation of pye.

A 'numeric' value specifying the penalization parameter for the regressors 'X'.

A 'numeric' value representing the cut-off point used to classify observations based on the combined biomarker score Z. Can be a single value (applied to all observations) or a numeric vector of length 'nrow(df)' for observation-specific cut-offs. Default is 0.

A 'numeric' value between 0 and 1 specifying the weight for the Weighted Youden Index. Sensitivity is weighted by 'w' and specificity by '1 - w'. Default is 0.5 (which corresponds to the standard Youden Index).

A 'character' string indicating the kernel type to use for the estimation of the density function. Currently, only "gaussian" is tested and supported. Default is "gaussian".

A 'numeric' value between 0 and 1, used as the mixing parameter for the Elastic-Net penalization term. Only relevant if 'penalty' is "EN". Default is 0.5.

A ‘numeric' value specifying the regularization parameter ’a' for the SCAD penalty (as defined in the original paper by Fan and Li). Only relevant if 'penalty' is "SCAD". Default is 3.7.

A ‘numeric' value specifying the regularization parameter ’gamma' for the MCP penalty (as defined in the original paper by Zhang). Only relevant if 'penalty' is "MCP". Default is 3.0.

A 'character' string indicating the type of penalty considered for the pye calculation. Must be one of "L12", "L1", "EN" (Elastic-Net), "SCAD", or "MCP". Default is "L1".

A 'numeric' value for the exponent of the bandwidth 'h' in the Kernel Smooth density estimation.

A 'logical' value. If 'TRUE', the function internally estimates and uses the optimal cut-off point 'c' based on the given betas. If 'FALSE' (default), the 'c' parameter provided directly is used.

A 'logical' value. If 'TRUE', the empirical maximum Youden Index is returned as the Youden index performance measure. This is useful for evaluating predictive performance on new data.

A 'logical' value. If 'TRUE', a plot of the Cumulative Distribution Functions (CDFs) for cases and controls, based on the combined regressor scores Z, will be printed. Default is 'FALSE'.

numeric. The Penalized Youden Index value using the L1 / 2 penalty.

numeric. The Penalized Youden Index value using the L1 penalty.

numeric. The Penalized Youden Index value using the Elastic-Net penalty.

numeric. The Penalized Youden Index value using the SCAD penalty.

numeric. The Penalized Youden Index value using the MCP penalty.

numeric vector. The gradient of the Youden Index with respect to the betas and the cut-off point 'c'. The last element corresponds to the gradient with respect to 'c'.

numeric. The unpenalized Youden Index calculated using the Kernel Smooth density estimator (or the empirical Youden Index if prediction = TRUE). It is weighted if w is not 0.5.

numeric. The sensitivity (True Positive Rate) for the given 'betas' and 'c'.

numeric. The specificity (True Negative Rate) for the given 'betas' and 'c'.

numeric. The geometric mean of sensitivity and specificity.

numeric. The False Discovery Rate (FP / (FP + TP)).

numeric. The Matthews Correlation Coefficient.

numeric. The Area Under the ROC Curve (AUC) for the given 'z_hat' scores.

numeric. The overall correct classification rate ((TP + TN) / N).

numeric. The optimal cut-off point 'c' suggested by the 'Youden' method from OptimalCutpoints package based on the empirical Youden Index.

numeric. The correct classification rate using the empirically suggested optimal cut-off point (empir_suggest_yi_c).

numeric. The Youden Index obtained using the empirically suggested optimal cut-off point (empir_suggest_yi_c).

data.frame with columns ID and c_hat. The cut-off point(s) used for each observation (either a single value repeated or input 'c').

data.frame with columns ID and z_hat. The combined biomarker scores (Z = X * betas) for each observation.

data.frame with columns ID and y_hat. The predicted binary outcomes (0 or 1) based on 'z_hat' and 'c_hat'.

numeric. Number of True Positives.

numeric. Number of True Negatives.

numeric. Number of False Positives.

numeric. Number of False Negatives.

list. A list containing the input parameters used for the calculation:

• beta (numeric vector): The input 'betas' coefficients.

• w (numeric vector): The input 'w' weighting parameter.

• lambda (numeric): The input 'lambda' penalization parameter.

• alpha (numeric): The input 'alpha' parameter for Elastic-Net.

• a1 (numeric): The input 'a1' parameter for SCAD.

• a2 (numeric): The input 'a2' parameter for MCP.

• prediction (logical): The input 'prediction' flag.

• c_hat (numeric or vector): The cut-off point(s) that were ultimately used (could be the input 'c' or 'empir_suggest_yi_c' if use_opt_c = TRUE).

• kernel (character): The kernel type used for density estimation.

A 'numeric' value specifying the number of folds for the cross-validation.

A 'data.frame' containing the input dataset. It must include the columns specified in 'X' and 'y', and optionally 'C'.

A 'character' vector specifying the names of the regressor variables (biomarkers) to consider in the estimation. Alternatively, a 'data.frame' containing only these regressors can be provided, in which case their column names will be used. Defaults to all columns in 'df' not specified as 'y' or 'C'.

A 'character' string specifying the name of the target binary variable (outcome). This variable must contain only values 0 and 1. Alternatively, a single-column 'data.frame' containing only the target variable can be provided, in which case its column name will be used. Default is "y".

A 'character' vector specifying the names of covariate variables. Alternatively, a 'data.frame' containing these covariates can be provided, in which case their column names will be used. Default is 'NULL', indicating no covariates are used.

A 'numeric' vector of penalization parameters for the regressors 'X'. The cross-validation will evaluate models across these lambda values.

A 'numeric' value between 0 and 1 specifying the weight for the Weighted Youden Index in pye. Sensitivity is weighted by 'w' and specificity by '1 - w'. Default is 0.5 (which corresponds to the standard Youden Index).

A 'numeric' value between 0 and 1 specifying the weight for the Weighted Youden Index in covYI. Sensitivity is weighted by 'w_g' and specificity by '1 - w_g'. Default is 0.5 (which corresponds to the standard Youden Index).

A 'numeric' value controlling the verbosity of the output. '0': no visualization; '1': visualize only the final result (default); '2': visualize all steps during optimization.

A 'numeric' value between 0 and 1, used as the mixing parameter for the Elastic-Net penalization term applied to 'X'. Only relevant if 'penalty' is "EN". Default is 0.5.

A 'numeric' value between 0 and 1, used as the mixing parameter for the Elastic-Net penalization term applied to covariates 'C' in covYI. Only relevant if 'penalty_g' is "EN". Default is 0.5.

A 'numeric' vector of penalization parameters for the covariates 'C' in covYI. If 0 (default), no penalization term is applied to covariates. If 'c_function_of_covariates' is 'TRUE', 'tau' cannot be 'NULL' or contain only zeros.

A ‘numeric' value specifying the regularization parameter ’a' for the SCAD penalty (as defined by Fan and Li). Only relevant if 'penalty' is "SCAD". Default is 3.7.

A ‘numeric' value specifying the regularization parameter ’gamma' for the MCP penalty (as defined by Zhang). Only relevant if 'penalty' is "MCP". Default is 3.0.

A 'character' string indicating the type of penalty considered for the pye calculation. Must be one of "L12", "L1", "EN" (Elastic-Net), "SCAD", or "MCP". Default is "L1".

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is 'NULL'.

A 'numeric' value to fix the random seed for reproducibility. Default is 1.

A 'numeric' value indicating the number of cores to use for parallelization. If equal to 1 (default), no parallelization is adopted.

A 'character' string indicating the optimization algorithm variant to use for pye estimation. If "monotone" (default), the Monotone Accelerated Proximal Gradient (mmAPG) algorithm is used. If "nonmonotone", the Non-Monotone Accelerated Proximal Gradient (mnmAPG) algorithm is used.

A 'numeric' value specifying the parameter for the convergence condition of the optimization algorithm for pye. Default is 1e-5.

A 'numeric' value representing the maximum allowed value for the step-size parameter 'alpha' in the backtracking line-search for pye optimization. Default is 10000.

A 'character' string indicating the kernel type to use for the estimation of the density function for pye. Currently, only "gaussian" is tested and supported. Default is "gaussian".

A 'numeric' vector of specific starting points for the beta coefficients. If 'NULL' (default), the starting points are determined by 'beta_start_default'. If provided, its length must match the number of regressors in 'X'.

A 'numeric' value specifying the maximum number of iterations for the optimization algorithms (mmAPG and mnmAPG) for pye. Default is 10000.

A 'numeric' value representing the minimum allowed value for the step-size parameter 'alpha' for pye optimization. Default is 1e-10.

A 'numeric' value specifying the error tolerance for considering the pye optimization algorithm converged. Default is 1e-7.

A 'numeric' value between 0 and 1, used to adjust the step-size in the backtracking line-search within the pye optimization. Values closer to 1 lead to higher accuracy but longer estimation times. Default is 0.8.

A 'character' string defining the default starting points for betas if 'beta_start_input' is 'NULL'. If "zeros" (default), betas start with a vector of all zeros. If "corr", betas start with the absolute value of the correlation of each regressor with the target variable 'y'.

A 'logical' value. If 'TRUE', the input dataset 'df' is scaled internally. If 'FALSE' (default), no scaling is performed.

A 'logical' value. If 'TRUE', the estimation process considers the cut-off point 'c' as fixed and equal to zero, which can reduce estimation complexity. If 'FALSE' (default), 'c' can vary and is estimated by the pye optimization.

A 'logical' value. If 'TRUE', covYI is used to estimate the cut-off point 'c' as a function of the covariate information ('C'). If 'FALSE' (default), covariate information is ignored for the cut-off estimation.

A 'logical' value. If 'c_function_of_covariates' is 'TRUE', this parameter defines if 'gammas' (covariate coefficients) need to be estimated simultaneously with 'betas' or as a second step. Default is 'FALSE', meaning a sequential estimation.

A 'character' string specifying the measure used to select 'lambda' if 'simultaneous' is 'FALSE' (i.e., when the cross-validation process selects 'lambda' first and then 'tau'). Must be one of "auc", "aauc", "aYI", "yi", "sen", "spc", "gm", "fdr", "mcc", or "ccr". Default is "ccr" (correct classification rate).

A 'character' string indicating the type of penalty for covYI (when 'c_function_of_covariates' is 'TRUE'). Must be one of "L12", "L1", "EN" (Elastic-Net), "SCAD", or "MCP". Default is "L1".

A 'character' string indicating the kernel type to use for the density estimation in covYI. Currently, only "gaussian" is tested and supported. Default is "gaussian".

A ‘numeric' value specifying the regularization parameter ’a' for the SCAD penalty in covYI. Only relevant if 'penalty_g' is "SCAD". Default is 3.7.

A ‘numeric' value specifying the regularization parameter ’gamma' for the MCP penalty in covYI. Only relevant if 'penalty_g' is "MCP". Default is 3.0.

A 'character' string indicating the optimization algorithm variant to use for covYI. If "monotone" (default), mmAPG is used. If "nonmonotone", mnmAPG is used.

A 'numeric' vector of specific starting points for the gamma coefficients in covYI. If 'NULL' (default), starting points are determined by 'gamma_start_default'.

A 'character' string defining the default starting point of gamma coefficients. If "zeros" (default), they start with all zero values. If "corr", they start with the absolute correlation of each covariate with the target variable.

A 'numeric' vector containing the true gamma coefficients (if known, for simulation/testing purposes). Default is 'NULL'.

A 'numeric' value specifying the maximum number of iterations for the optimization algorithms (mmAPG and mnmAPG) in covYI. Default is 10000.

A 'numeric' value specifying the parameter for the convergence condition of the optimization algorithm of covYI. Default is 1e-5.

A 'numeric' value representing the maximum allowed value for the step-size parameter 'alpha' in covYI. Default is 10000.

A 'numeric' value between 0 and 1, used to adjust the step-size in the backtracking line-search within the covYI optimization. Values closer to 1 lead to higher accuracy but longer estimation times. Default is 0.8.

A 'numeric' value representing the minimum allowed value for the step-size parameter 'alpha' in covYI. Default is 1e-12.

A 'numeric' value specifying the error tolerance for considering the covYI algorithm converged. Default is 1e-7.

A 'logical' value. If 'FALSE' (default), the aAUC and aYI measures are not computed, saving estimation time if not requested.

Character. Path to a file for logging output from parallel workers. If 'NULL', output goes to the console. Default is "log_pye_ks_models.txt".

character. The type of penalty used for regressors X.

character. The type of penalty used for covariates C (if applicable).

character. The kernel type used for density estimation of pye.

difftime. The total time taken for the cross-validation process, in minutes.

list. For each penalty type, a list containing 'train' and 'test' matrices. These matrices store the Penalized Youden Index values for each fold and each combination of 'lambda' and 'tau' (if applicable). Their dimensions are 'n_folds' rows by 'length(tau)' columns (or 1 if 'length(tau)' is 1).

list. Similar to 'pye_KS_penalty' components, these lists contain 'train' and 'test' matrices for each respective performance measure (AUC, adaptive AUC, adaptive Youden Index, unpenalized Youden Index, sensitivity, specificity, geometric mean, false discovery rate, Matthews Correlation Coefficient, and correct classification rate) of the first-step method and of the final method (which coincide if c_function_of_covariates is FALSE), across all folds and 'lambda'/'tau' combinations.

numeric. The optimal 'lambda' value selected based on maximizing the corresponding performance measure (e.g., '_yi' for Youden Index, '_auc' for AUC). If no optimal lambda is found, it will be 'NA'.

numeric. The optimal 'tau' value selected based on maximizing the corresponding performance measure. This is only relevant and will be a value other than 'NA' if 'c_function_of_covariates' is 'TRUE'. Otherwise, it will be 'NA'.

logical. Indicates whether the cut-off point was estimated as a function of covariates.

logical. Indicates whether betas and gammas were estimated simultaneously (if 'c_function_of_covariates' was 'TRUE').

character. The measure used to select the optimal 'lambda' (if 'simultaneous' is 'FALSE').

numeric. The single optimal lambda value chosen (when 'c_function_of_covariates' is 'TRUE' and 'simultaneous' is 'FALSE'), based on 'measure_to_select_lambda'. 'NA' otherwise.

matrix. A matrix showing the number of non-zero (selected) betas for each fold and each 'lambda' value. Its dimensions are 'n_folds' rows by 'length(lambda)' columns.

matrix. If a two-step optimization (sequential lambda then tau) is performed ('c_function_of_covariates = TRUE' and 'simultaneous = FALSE'), this matrix shows the number of non-zero betas for each fold using 'lambda_star'. Dimensions are 'n_folds' rows by 1 column.

list. A list, where each element corresponds to a 'lambda' value and contains a matrix showing the number of non-zero (selected) gammas for each fold and each 'tau' value. Dimensions are 'n_folds' rows by 'length(tau)' columns.

matrix or list. The estimated beta coefficients. If 'length(lambda)' is 1, a matrix with 'n_folds' rows. Otherwise, a list of beta vectors for each fold and each lambda.

list. A list where each element corresponds to a lambda value and contains a matrix showing the estimated optimal cut-off point c for each fold and each lambda value. If c_zero_fixed is TRUE, all entries will be 0.

matrix or list. If a two-step optimization is performed, the estimated beta coefficients using 'lambda_star'. A matrix with 'n_folds' rows if 'length(lambda_star)' is 1, otherwise a list of beta vectors.

list. A list, where each element corresponds to a 'lambda' value (or 'lambda_star' if sequential) and contains a matrix or vector of estimated gamma coefficients for each fold and 'tau' value.

A 'data.frame' containing the input dataset. Must include the columns specified in 'X' and 'y'.

A 'character' vector specifying the names of the regressor variables (biomarkers) to consider in the estimation. Alternatively, a 'data.frame' containing only these regressors can be provided, in which case their column names will be used. Default is all columns in 'df' not specified as 'y'.

A 'character' string specifying the name of the target binary variable (outcome). This variable must contain only values 0 and 1. Alternatively, a single-column 'data.frame' containing only the target variable can be provided, in which case its column name will be used. Default is "y".

A 'numeric' value specifying the penalization parameter for the regressors 'X'. Must be a single non-negative value.

A 'character' string indicating the type of penalty to apply. Must be one of "L12", "L1", "EN" (Elastic-Net), "SCAD", or "MCP". Default is "L1".

A 'numeric' value between 0 and 1 specifying the weight for the Weighted Youden Index. Sensitivity is weighted by 'w' and specificity by '1 - w'. Default is 0.5.

A 'numeric' vector of specific starting points for the beta coefficients. If 'NULL' (default), the starting points are determined by 'beta_start_default'. If provided, its length must match the number of regressors in 'X'.

A 'character' string defining the default starting points for betas if 'beta_start_input' is 'NULL'. If "zeros" (default), betas start with a vector of all zeros. If "corr", betas start with the absolute value of the correlation of each regressor with the target variable 'y'.

The number of elements to show when printing results. Default is 10.

A 'numeric' value between 0 and 1, used as the mixing parameter for the Elastic-Net penalization term. Only relevant if 'penalty' is "EN". Default is 0.5.

A ‘numeric' value specifying the regularization parameter ’a' for the SCAD penalty (as defined in the original paper by Fan and Li). Only relevant if 'penalty' is "SCAD". Default is 3.7.

A ‘numeric' value specifying the regularization parameter ’gamma' for the MCP penalty (as defined in the original paper by Zhang). Only relevant if 'penalty' is "MCP". Default is 3.0.

numeric vector. An optional vector containing the "true" beta coefficients, if known. This is used to calculate additional performance measures related to variable selection accuracy. Default is 'NULL'.

numeric. An optional fold number, used when the function is called within a cross-validation loop. This is primarily for tracking and reporting purposes. Default is 'NULL'.

A 'numeric' value specifying the maximum number of iterations for the optimization algorithms (mmAPG and mnmAPG). Default is 10000.

A 'character' string indicating the optimization algorithm variant to use. If "monotone" (default), the Monotone Accelerated Proximal Gradient (mmAPG) algorithm is used. If "nonmonotone", the Non-Monotone Accelerated Proximal Gradient (mnmAPG) algorithm is used.

A 'numeric' value specifying the parameter for the convergence condition of the optimization algorithm. Default is 1e-5.

A 'numeric' value representing the maximum allowed value for the step-size parameter 'alpha' in the backtracking line-search. Default is 10000.

A 'numeric' value between 0 and 1, used to adjust the step-size in the backtracking line-search within the optimization of pye. Values closer to 1 lead to higher accuracy but longer estimation times. Default is 0.8.

A 'numeric' value representing the minimum allowed value for the step-size parameter 'alpha'. Default is 1e-10.

A 'numeric' value specifying the error tolerance for considering the optimization algorithm converged. Default is 1e-7.

A 'numeric' value controlling the verbosity of the output. 0: no visualization, 1: visualize only the final result (default), 2: visualize all steps during optimization.

A 'numeric' value to fix the random seed for reproducibility. Default is 1.

A 'logical' value. If 'TRUE', the estimation process considers the cut-off point 'c' as fixed and equal to zero, which can reduce estimation complexity. If 'FALSE' (default), 'c' can vary and is estimated by the pye optimization.

A 'character' string indicating the kernel type to use for the estimation of the density function. Currently, only "gaussian" is tested and supported. Default is "gaussian".

A 'numeric' value specifying the iteration number from which parameters that have reached zero in the estimation cannot change (i.e., remain zero) anymore. This helps preserve the sparsity of the solution. Default is 20.

numeric vector. The estimated optimal coefficients (betas) for the regressors X, with penalty replaced by the actual penalty used (e.g., betas_hat_L1). Non-zero values indicate selected features.

numeric. The optimized Penalized Youden Index (pye) value achieved for the given penalty (e.g., pye_KS_L1).

numeric vector. The gradient of the Youden Index at the estimated optimal point.

numeric. The penalization parameter used in the estimation.

character. The type of penalty used for regularization (e.g., "L1", "SCAD").

numeric vector. The initial starting point for the betas used in the optimization algorithm.

character. The kernel type used for density estimation (e.g., "gaussian").

numeric. The estimated optimal cut-off point 'c'.

data.frame with columns ID and z_hat. The combined biomarker scores (Z = X * betas) for each observation based on the estimated betas_hat.

data.frame with columns ID and y_hat. The predicted binary outcomes (0 or 1) based on z_hat and c_hat.

numeric. The unpenalized Youden Index calculated using the Kernel Smooth density estimator at the estimated optimal point.

numeric. The sensitivity (True Positive Rate) at the estimated optimal point.

numeric. The specificity (True Negative Rate) at the estimated optimal point.

numeric. The geometric mean of sensitivity and specificity at the estimated optimal point.

numeric. The False Discovery Rate (FP / (FP + TP)) at the estimated optimal point.

numeric. The Matthews Correlation Coefficient at the estimated optimal point.

numeric. The Area Under the ROC Curve (AUC) for the z_hat scores at the estimated optimal point.

numeric. The overall correct classification rate ((TP + TN) / N) at the estimated optimal point.

numeric. The number of non-zero (selected) betas in the final estimation.

numeric. The total number of regressors considered (length of X).

numeric. The number of estimated betas that are exactly zero.

numeric. The number of estimated betas that are non-zero.

numeric or NA. If regressors_betas is provided, the number of true non-zero betas correctly estimated as non-zero. Otherwise NA.

numeric or NA. If regressors_betas is provided, the number of true non-zero betas incorrectly estimated as zero. Otherwise NA.

numeric or NA. If regressors_betas is provided, the number of true zero betas correctly estimated as zero. Otherwise NA.

numeric or NA. If regressors_betas is provided, the number of true zero betas incorrectly estimated as non-zero. Otherwise NA.

character vector. A list containing the input parameters.

difftime. The total time taken for the estimation process, in minutes.

numeric. The total number of iterations performed by the optimization algorithm (mmAPG or mnmAPG).

An integer, the number of simulation experiments to run. Default is 1000.

A data frame containing the complete dataset (y, X, C).

A character vector of column names from 'df' for regressors in the pye KS model. Defaults to all columns not 'y' or 'C'.

A character string, the column name for the binary target variable (0 or 1). Default is "y".

A character vector of column names from 'df' for covariates in the covYI model. Default is 'NULL'.

A numeric value, the penalization parameter \lambda for regressors X (pye KS model).

A numeric value, the penalization parameter \tau for covariates C (covYI model). Default is 0 (no penalization).

A numeric value between 0 and 1 specifying the weight for the Weighted Youden Index in pye. Sensitivity is weighted by 'w' and specificity by '1 - w'. Default is 0.5 (which corresponds to the standard Youden Index).

A numeric value between 0 and 1 specifying the weight for the Weighted Youden Index in covYI. Sensitivity is weighted by 'w_g' and specificity by '1 - w_g'. Default is 0.5 (which corresponds to the standard Youden Index).

A numeric value between 0 and 1. The proportion of the total observations in 'df' to be used for the training set in each simulation split. The split is performed using stratified sampling on 'y' to maintain class balance. Default is 0.7 (70% training, 30% testing).

A numeric vector for custom starting \beta coefficients. Default is 'NULL'.

A character string for default starting \betas if 'beta_start_input' is 'NULL'. Options: "zeros", "corr". Default is "zeros".

An integer (0, 1, or 2) controlling output verbosity. 0=none, 1=main, 2=all steps. Default is 1.

A numeric value [0, 1], the elastic-net mixing parameter for pye KS. Default is 0.5.

A numeric value, the $a$ parameter for SCAD/MCP in pye KS. Default is 3.7.

A numeric value, the $b$ parameter for MCP in pye KS. Default is 3.0.

character. The penalty type for regressors (X) in pye. Options: "L12", "L1" (Lasso), "EN" (Elastic-Net), "SCAD", and "MCP". Default is "L1".

numeric vector. The "true" \beta coefficients, if known, for variable selection accuracy. Default is 'NULL'.

An integer specifying CPU cores for parallelization. 0 uses 70\% of available cores. Default is 1 (no parallel).

A logical value. If 'TRUE', the dataset 'df' is scaled before processing. Default is 'FALSE'.

A logical value. If 'TRUE', the cut-off point c is fixed at zero. Default is 'FALSE'.

An integer, max iterations for pye KS optimization. Default is 10000.

A character string specifying the pye KS optimization algorithm trend. Options: "monotone" (mmAPG), "nonmonotone" (mnmAPG). Default is "monotone".

A numeric value, convergence tolerance for pye KS. Default is 1e-5.

A numeric value, max step-size for pye KS backtracking. Default is 10000.

A numeric value [0, 1], shrinkage factor for pye KS backtracking step-size. Default is 0.8.

A numeric value, min step-size for pye KS backtracking. Default is 1e-10.

A numeric value, the convergence threshold in pye KS. Default is 1e-7.

A character string specifying the kernel type for pye KS density estimation (e.g., "gaussian"). Default is "gaussian".

A logical value. If 'TRUE', covYI is used to estimate cut-off c as a function of C. Default is 'FALSE'.

A numeric value [0, 1], the elastic-net mixing parameter for covYI. Default is 0.5.

A character string specifying the penalty type for covYI. Must be "L12", "L1", "EN", "SCAD", or "MCP". Default is "L1".

A character string specifying the kernel type for covYI density estimation. Default is "gaussian".

A numeric value, the $a$ parameter for SCAD/MCP in covYI. Default is 3.7.

A numeric value, the $b$ parameter for MCP in covYI. Default is 3.0.

A character string specifying the covYI optimization algorithm trend. Default is "monotone".

A numeric vector for custom starting \gamma coefficients. Default is 'NULL'.

A character string for default starting \gammas if 'gamma_start_input' is 'NULL'. Options: "zeros", "corr". Default is "zeros".

A numeric vector representing the true \gamma coefficients (if known), for evaluation. Default is 'NULL'.

An integer, max iterations for covYI optimization. Default is 10000.

A numeric value, convergence tolerance for covYI. Default is 1e-5.

A numeric value, max step-size for covYI backtracking. Default is 10000.

A numeric value [0, 1], shrinkage factor for covYI backtracking step-size. Default is 0.8.

A numeric value, min step-size for covYI backtracking. Default is 1e-12.

A numeric value, the convergence threshold in covYI. Default is 1e-7.

A logical value. If 'FALSE', aAUC and aYI measures are not computed to save time. Default is 'FALSE'.

Character. Path to a file for logging parallel output. Default is "log_sim_pye_real.txt".

Total time taken for the entire simulation (time unit is in the output).

Mean estimation time for the pye KS model across all simulations.

Mean estimation time for the covYI model, if c_function_of_covariates is TRUE.

Number of CPU cores used for parallel processing.

Number of simulation experiments performed.

The penalization parameters used for X and C respectively.

Matrices (n x 2, for train/test) containing the pye KS objective function values, based on the selected penalty and the fitted betas.

Matrices (n x 2, for train/test) of classification performance measures for the pye KS model.

Matrices (n x 2, for train/test) of classification performance measures for the covYI model, if c_function_of_covariates is TRUE.

Matrices related to variable selection performance (comparison with regressors_betas), where relevant.

Matrices related to variable selection performance for gammas (comparison with regressors_gammas), if c_function_of_covariates is TRUE.

A vector counting the number of times (out of n) each X regressor was estimated as non-zero.

A vector counting the number of times (out of n) each C covariate was estimated as non-zero, if c_function_of_covariates is TRUE.

The starting beta coefficients used.

A logical value indicating if the cut-off point c was fixed at zero.

A vector of specificity points (e.g., seq(0, 1, by = 0.05)) used to compute the ROC curves.

A list where each element contains the sensitivity points corresponding to roc_spec_points on the training data for each simulation.

A list where each element contains the sensitivity points corresponding to roc_spec_points on the testing data for each simulation.

The true regressor vectors used for evaluation (if provided).

character vector. A list containing the input parameters.

The input parameters indicating if covYI was used and if advanced AUC metrics were run.

A list containing the vector of estimated beta coefficients from each simulation run.

A list containing the vector of estimated gamma coefficients from each simulation run, if c_function_of_covariates is TRUE.

A data.frame or tibble containing all variables.

A character vector of column names considered as potential regressors. Only numeric variables from this list will be scaled.

A character string: the name of the target variable. This variable will not be scaled.

A data.frame with the selected numeric regressors scaled (centered to mean 0 and scaled to SD 1).

A list containing:

• original_mu: Means of the variables that were scaled.

• original_stdev: Standard deviations of the variables.

These parameters enable consistent scaling of new data.