Package {triageR}

Fit a clinical survival (time-to-event) model

Description

triageR: Survival Analysis Utilities

Author(s)

Maintainer: Uwakmfon Paul uwakmfon31@gmail.com [copyright holder]

Authors:

• Uwakmfon Paul uwakmfon31@gmail.com [copyright holder]

See Also

Useful links:

• https://github.com/DevWebWacky/triageR

• https://devwebwacky.github.io/triageR/

• Report bugs at https://github.com/DevWebWacky/triageR/issues

Review a clinical modelling pipeline for common pitfalls

Description

Runs a series of rule-based checks for common clinical-ML pitfalls (class imbalance or low event rate, low events-per-variable, possible leakage, near-zero variance predictors), then optionally asks an LLM to summarize the findings in plain language. Works with both binary classification models (triageR_model) and survival models (triageR_survival_model).

Usage

tr_agent_review(data, model, use_agent = TRUE)

Arguments

Value

A triageR_review object (list) containing a tibble of flags and, if use_agent = TRUE, an AI-generated summary.

Examples

## Not run: 
tr_agent_review(data, model)

## End(Not run)

Check missing data in a clinical dataset

Description

Produces a summary table of missingness per column, plus a visual plot showing the pattern of missing data across the dataset.

Usage

tr_check_missing(data)

Arguments

Value

Invisibly returns a summary tibble (columns, n_missing, pct_missing). Also prints a summary to console and displays a missingness plot as a side effect.

Examples

df <- data.frame(a = c(1, NA, 3), b = c(4, 5, NA))
tr_check_missing(df)

Explain a clinical prediction model

Description

Generates variable importance or prediction explanations for a fitted triageR_model, using the DALEX framework under the hood.

Usage

tr_explain(
  model,
  method = c("permutation", "shap"),
  newdata = NULL,
  observation = 1
)

Arguments

Value

A triageR_explanation object (list) containing the explanation result and a plot.

Examples

## Not run: 
tr_explain(model, method = "permutation")
tr_explain(model, method = "shap", observation = 3)

## End(Not run)

Fit a clinical prediction model

Description

Fits a binary classification model using the parsnip/workflows framework. The user must specify the model engine explicitly.

Usage

tr_fit(
  data,
  outcome,
  engine = c("logistic_reg", "random_forest", "boost_tree"),
  predictors = NULL
)

Arguments

Value

A fitted triageR_model object — a list containing the fitted workflow, the engine used, and the outcome/predictor names.

Examples

set.seed(1)
df <- data.frame(
  age = round(rnorm(50, 55, 12)),
  sex = sample(c("M", "F"), 50, replace = TRUE),
  disease = sample(c(0, 1), 50, replace = TRUE)
)
model <- tr_fit(df, outcome = "disease", engine = "logistic_reg")

Fits a survival model using the censored/parsnip framework. The outcome must be specified as separate time and event columns (following survival::Surv() convention), and the user must explicitly choose an engine.

Description

Fits a survival model using the censored/parsnip framework. The outcome must be specified as separate time and event columns (following survival::Surv() convention), and the user must explicitly choose an engine.

Usage

tr_fit_survival(
  data,
  time_col,
  event_col,
  engine = c("cox_ph", "survival_rf"),
  predictors = NULL
)

Arguments

Value

A fitted triageR_survival_model object (list) containing the fitted workflow, engine, and time/event/predictor column names.

Examples

if (requireNamespace("survival", quietly = TRUE)) {
  library(survival)
  lung_clean <- lung
  lung_clean$status <- lung_clean$status - 1  # convert 1/2 to 0/1
  lung_clean <- lung_clean[stats::complete.cases(lung_clean), ]
  model <- tr_fit_survival(lung_clean, time_col = "time",
                            event_col = "status", engine = "cox_ph")
}

Impute missing values in a clinical dataset

Description

Fills in missing values using either multiple imputation (mice) or a random-forest based approach (missForest). The method must be chosen explicitly, this function does not guess for you.

Usage

tr_impute(data, method = c("mice", "missForest"), m = 5, seed = 123)

Arguments

Value

A completed data frame with missing values filled in. If method = "mice", the first completed dataset is returned, and the full mids object is attached as an attribute ("mice_object") in case the user wants to inspect all imputations.

Examples

df <- data.frame(
  a = c(5, 7, 3, 9, 2, 8, 6, 4, 5, 7),
  b = c(1, 3, 2, 4, 5, 3, 2, NA, 1, 3)
)
completed <- tr_impute(df, method = "mice", m = 2)

Launch the triageR Shiny app

Description

Opens an interactive Shiny application for building, validating, and reporting clinical prediction models without writing R code directly. Supports data upload, model fitting across multiple engines, validation, explainability, automated pipeline review, and TRIPOD+AI report generation. The AI method-recommendation feature requires a configured Gemini API key (see ?tr_recommend_method) and is optional.

Usage

tr_launch_app()

Value

Does not return; launches a Shiny application.

Examples

if (interactive()) {
  tr_launch_app()
}

Load and standardize a clinical dataset

Description

Reads a flat clinical dataset (CSV or data frame) and returns it as a standardized triageR object with basic structure checks. This is the entry point for most triageR workflows.

Usage

tr_load_clinical(data, id_col = "id")

Arguments

Value

A tibble of class triageR_data, with basic metadata attached.

Examples

df <- data.frame(
  id = 1:5,
  age = c(45, 62, 38, 71, 55),
  sex = c("F", "M", "F", "M", "F")
)
tr_load_clinical(df, id_col = "id")

Recommend an appropriate statistical or ML method (AI agent)

Description

Uses an LLM to inspect the structure of a clinical dataset and suggest an appropriate statistical or machine learning approach, with reasoning. This is an assistive tool, not a replacement for expert judgment.

Usage

tr_recommend_method(data, outcome, context = NULL)

Arguments

Value

Invisibly returns the raw text recommendation (character string). Also prints the recommendation to console.

Examples

## Not run: 
tr_recommend_method(data, outcome = "disease",
  context = "predicting diabetes onset in adults")

## End(Not run)

Run an automated sensitivity analysis battery

Description

Re-fits a clinical prediction model under several robustness checks, complete-case vs imputed data, outlier exclusion, and subgroup consistency, and compares performance metrics across them.

Usage

tr_sensitivity(data, model, subgroup_col = NULL, outlier_sd = 3)

Arguments

Value

A triageR_sensitivity object (list) with a comparison tibble of metrics across all sensitivity scenarios.

Examples

## Not run: 
tr_sensitivity(data, model, subgroup_col = "sex")

## End(Not run)

Generate a TRIPOD+AI-aligned clinical model report

Description

Renders a reproducible report summarizing model fit, validation, sensitivity analysis, and pipeline review, aligned with TRIPOD+AI reporting guidance. Supports both binary classification and survival models. This is a drafting aid, not a certified compliance tool.

Usage

tr_tripod_report(
  model,
  model_type = c("classification", "survival"),
  validation = NULL,
  review = NULL,
  sensitivity = NULL,
  recommendation = NULL,
  output_file = file.path(tempdir(), "triageR_report"),
  format = c("html", "docx")
)

Arguments

Value

Invisibly returns the path to the rendered report file.

Examples

## Not run: 
tr_tripod_report(model, validation = val, review = rev,
  output_file = file.path(tempdir(), "report"))

## End(Not run)

Validate a clinical prediction model

Description

Computes discrimination (AUC, sensitivity, specificity) and calibration metrics for a fitted triageR_model. Can validate on new (external/holdout) data, or fall back to the training data with a clear warning.

Usage

tr_validate(
  model,
  newdata = NULL,
  threshold = 0.5,
  calibration_method = c("binned", "smooth")
)

Arguments

Value

A triageR_validation object (list) containing a metrics tibble and the underlying predictions, invisibly printed as a summary.

Examples

set.seed(1)
df <- data.frame(
  age = round(rnorm(50, 55, 12)),
  sex = sample(c("M", "F"), 50, replace = TRUE),
  disease = sample(c(0, 1), 50, replace = TRUE)
)
model <- tr_fit(df, outcome = "disease", engine = "logistic_reg")
tr_validate(model, newdata = df)

Validate a clinical survival model

Description

Computes the concordance index (C-index) for a fitted triageR_survival_model — the survival-analysis equivalent of AUC, measuring how well the model ranks patients by risk. Can validate on new (external/holdout) data, or fall back to the training data with a clear warning.

Usage

tr_validate_survival(model, newdata = NULL)

Arguments

Value

A triageR_survival_validation object (list) containing the C-index and supporting details.

Examples

if (requireNamespace("survival", quietly = TRUE)) {
  library(survival)
  lung_clean <- lung
  lung_clean$status <- lung_clean$status - 1
  lung_clean <- lung_clean[stats::complete.cases(lung_clean), ]
  model <- tr_fit_survival(lung_clean, time_col = "time",
                            event_col = "status", engine = "cox_ph")
  tr_validate_survival(model, newdata = lung_clean)
}