Package {triageR}

Review a clinical modelling pipeline for common pitfalls

Description

Runs a series of rule-based checks for common clinical-ML pitfalls (class imbalance, low events-per-variable, possible leakage, near-zero variance predictors), then optionally asks an LLM to summarize the findings in plain language.

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")

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)

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. This is a drafting aid, not a certified compliance tool.

Usage

tr_tripod_report(
  model,
  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)

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)