Package 'clinpubr'

Description

Combine lists by adding element-wise.

Usage

add_lists(l1, l2)

Arguments

Value

A list.

Examples

l1 <- list(a = 1, b = 2)
l2 <- list(a = 3, b = 4, c = 5)
add_lists(l1, l2)

Description

Check answers of multiple choice questions by matching the answers with the correct sequence.

Usage

answer_check(dat, seq, multi_column = FALSE)

Arguments

Details

If multi_column is TRUE, the answers for Multiple-Answer Questions should be in multiple columns of logicals, with each column representing a choice. The seq should be a string of "T" and "F". If multi_column is FALSE, the answers for Multiple-Answer Questions should be in one column, and the function would expect an exact match of seq.

Value

A data frame of boolean values, with ncol equals the number of questions.

Examples

dat <- data.frame(Q1 = c("A", "B", "C"), Q2 = c("AD", "AE", "ABF"))
seq <- c("A", "AE")
answer_check(dat, seq)
dat <- data.frame(
  Q1 = c("A", "B", "C"), Q2.A = c(TRUE, TRUE, FALSE),
  Q2.B = c(TRUE, FALSE, TRUE), Q2.C = c(FALSE, TRUE, FALSE)
)
seq <- c("A", "TFT")
answer_check(dat, seq, multi_column = TRUE)

Description

Create a baseline table and a table of missing values. If the strata variable has more than 2 levels, a pairwise comparison table will also be created.

Usage

baseline_table(
  data,
  var_types = NULL,
  strata = NULL,
  vars = NULL,
  factor_vars = NULL,
  exact_vars = NULL,
  nonnormal_vars = NULL,
  seed = NULL,
  omit_missing_strata = FALSE,
  save_table = FALSE,
  filename = NULL,
  multiple_comparison_test = TRUE,
  p_adjust_method = "BH",
  smd = FALSE,
  ...
)

Arguments

Value

A list containing the baseline table and accompanying tables.

Examples

withr::with_tempdir(
  {
    data(cancer, package = "survival")
    var_types <- get_var_types(cancer, strata = "sex")
    baseline_table(cancer, var_types = var_types, filename = "baseline.csv")

    # baseline table with pairwise comparison
    cancer$ph.ecog_cat <- factor(cancer$ph.ecog,
      levels = c(0:3),
      labels = c("0", "1", ">=2", ">=2")
    )
    var_types <- get_var_types(cancer, strata = "ph.ecog_cat")
    baseline_table(cancer, var_types = var_types, save_table = TRUE, filename = "baseline.csv")
    print(paste0("files saved to: ", getwd()))
  },
  clean = FALSE
)

Description

Generate breaks for histogram that covers xlim and includes a ref_val.

Usage

break_at(xlim, breaks, ref_val = NULL)

Arguments

Value

A vector of breaks of length breaks + 1.

Examples

break_at(xlim = c(0, 10), breaks = 12, ref_val = 3.12)

Description

Calculate C-index for survival data. It's a wrapper function for Hmisc::rcorr.cens().

Usage

calc_cindex(data, time_var, event_var, marker_var)

Arguments

Value

The C-index value.

Examples

# Calculate C-index using lung dataset from survival package
data(cancer, package = "survival")
# Use age as the marker variable
calc_cindex(lung, "time", "status", "age")

Description

Calculate an index based on multiple conditions. Each condition is evaluated and the result is weighted and summed to produce the final index.

Usage

calculate_index(.df, ..., .weight = 1, .na_replace = 0)

Arguments

Value

A numeric vector of index scores

Examples

df <- data.frame(x = c(1, 2, 3, 4, 5), y = c(1, 2, NA, 4, NA))
calculate_index(df, x > 3, y < 3, .weight = c(1, 2), .na_replace = 0)

Description

Finds the elements that cannot be converted to numeric in a character vector. Useful when setting the strategy to clean numeric values.

Usage

check_nonnum(
  x,
  return_idx = FALSE,
  show_unique = TRUE,
  max_count = NULL,
  random_sample = FALSE,
  fix_len = FALSE
)

Arguments

Details

The function uses the as.numeric() function to try to convert the elements to numeric. If the conversion fails, the element is considered non-numeric.

Value

The (unique) elements that cannot be converted to numeric, and their indexes if return_idx is TRUE.

Examples

check_nonnum(c("\uFF11\uFF12\uFF13", "11..23", "3.14", "2.131", "35.2."))

Description

Compare the performance of classification models by commonly used metrics, and generate commonly used plots including receiver operating characteristic curve plot, decision curve analysis plot, and calibration plot.

Usage

classif_model_compare(
  data,
  target_var,
  model_names,
  colors = NULL,
  save_output = FALSE,
  figure_type = "png",
  output_prefix = "model_compare",
  as_probability = FALSE,
  auto_order = TRUE
)

Arguments

Value

A list of various results. If the output files are not in desired format, these results can be modified for further use.

• metric_table: A data frame containing the performance metrics for each model.

• roc_plot: A ggplot object of Receiver Operating Characteristic curves.

• pr_plot: A ggplot object of Precision-Recall curves.

• dca_plot: A ggplot object of decision curve analysis plots.

• calibration_plot: A ggplot object of calibration plots.

Metrics

• AUC: Area Under the Receiver Operating Characteristic Curve

• PRAUC: Area Under the Precision-Recall Curve

• Accuracy: Overall accuracy

• Sensitivity: True positive rate

• Specificity: True negative rate

• Pos Pred Value: Positive predictive value

• Neg Pred Value: Negative predictive value

• F1: F1 score

• Kappa: Cohen's kappa

• Brier: Brier score

• cutoff: Optimal cutoff for classification, metrics that require a cutoff are based on this value.

• Youden: Youden's J statistic

• HosLem: Hosmer-Lemeshow test p-value

Examples

data(cancer, package = "survival")
df <- kidney
df$dead <- ifelse(df$time <= 100 & df$status == 0, NA, df$time <= 100)
df <- na.omit(df[, -c(1:3)])

model0 <- glm(dead ~ age + frail, family = binomial(), data = df)
model <- glm(dead ~ ., family = binomial(), data = df)
df$base_pred <- predict(model0, type = "response")
df$full_pred <- predict(model, type = "response")

classif_model_compare(df, "dead", c("base_pred", "full_pred"), save_output = FALSE)

Description

combine multiple data files into a single data frame

Usage

combine_files(
  path = ".",
  pattern = NULL,
  recursive = FALSE,
  add_file_name = FALSE,
  unique_only = TRUE,
  reader_fun = read.csv,
  ...
)

Arguments

Value

A data frame. If no data files found, return NULL.

Examples

library(withr)
with_tempdir({
  write.csv(data.frame(x = 1:3, y = 4:6), "file1.csv", row.names = FALSE)
  write.csv(data.frame(x = 7:9, y = 10:12), "file2.csv", row.names = FALSE)
  dat <- combine_files(pattern = "file")
})
print(dat)

Description

Combine multi-choice columns into one, each column consists of booleans whether a choice is presented.

Usage

combine_multichoice(
  df,
  quest_cols,
  sep = ",",
  remove_cols = TRUE,
  remove_prefix = TRUE
)

Arguments

Value

A data frame with additional columns.

Examples

# Single group (backward compatibility)
df <- data.frame(q1 = c(TRUE, FALSE, TRUE), q2 = c(FALSE, TRUE, TRUE))
combine_multichoice(df, quest_cols = c("q1", "q2"))

# Multiple groups with named list
df <- data.frame(
  a1 = c(TRUE, FALSE, TRUE), a2 = c(FALSE, TRUE, TRUE),
  b1 = c(TRUE, TRUE, FALSE), b2 = c(FALSE, FALSE, TRUE)
)
combine_multichoice(df, quest_cols = list(groupA = c("a1", "a2"), groupB = c("b1", "b2")))

Description

Get common prefix of a string vector

Usage

common_prefix(x)

Arguments

Value

A string that is the common prefix of the input vector.

Examples

common_prefix(c("Q1_a", "Q1_b", "Q1_c"))

Description

Divide numeric data into different groups. Easier to use than base::cut().

Usage

cut_by(
  x,
  breaks,
  breaks_as_quantiles = FALSE,
  group = NULL,
  labels = NULL,
  label_type = "ori",
  right = FALSE,
  drop_empty = TRUE,
  verbose = FALSE,
  ...
)

Arguments

Details

cut_by() is a wrapper for base::cut(). Compared with the argument breaks in base::cut(), breaks here automatically sets the minimum and maximum. breaks outside the range of x are not allowed.

Value

A factor.

Note

The argument right in base::cut() is always set to FALSE, which means the levels follow the left closed right open convention.

Examples

set.seed(123)
cut_by(rnorm(100), c(0, 1, 2))
cut_by(rnorm(100), c(1 / 3, 2 / 3), breaks_as_quantiles = TRUE, label_type = "LMH")

Description

This function provides a comprehensive overview of a data.frame, including variable types, summary statistics, and potential data quality issues. It serves as a starting point for data cleaning by identifying problems that need attention.

Usage

data_overview(
  df,
  outlier_method = "iqr",
  outlier_threshold = NULL,
  verbose = TRUE,
  sample = 10000
)

Arguments

Value

A list containing:

• variable_types: Classification of variables by type

• summary_stats: Summary statistics for each variable

• quality_issues: Identified data quality problems

• recommendations: Suggestions for data cleaning

Examples

# Basic usage
data(mtcars)
overview <- data_overview(mtcars)
print(overview$variable_types)
print(overview$quality_issues)

Description

Detect outliers in a numeric vector using various methods.

Usage

detect_outliers(x, method = "iqr", threshold = NULL)

Arguments

Details

This function provides a unified interface for detecting outliers using different methods.

• "mad": Median absolute deviation method

• "iqr": Interquartile range method

• "zscore": Z-score method

Value

A list containing:

• outlier_mask: Logical vector indicating outliers, NA for missing values

• outlier_count: Number of outliers detected

• outlier_pct: Percentage of outliers in the data

• summary: Summary statistics including:

  • Before removing outliers: max, min, variance

  • After removing outliers: max, min, variance

  • Method-specific details

See Also

mad_outlier, iqr_outlier, zscore_outlier

Examples

x <- c(1, 2, 3, 4, 5, 100)
detect_outliers(x, method = "iqr")

Description

Shows the non-numeric elements in a data frame. Only character columns are checked. Useful when setting the strategy to clean numeric values.

Usage

df_view_nonnum(
  df,
  max_count = 20,
  random_sample = FALSE,
  long_df = FALSE,
  subject_col = NULL,
  value_col = NULL
)

Arguments

Value

A data frame of the non-numeric elements.

Examples

df <- data.frame(
  x = c("1", "2", "3..3", "4", "6a"),
  y = c("1", "ss", "aa.a", "4", "xx"),
  z = c("1", "2", "3", "4", "6")
)
df_view_nonnum(df)

Description

default color palette for clinpubr plots

Usage

emp_colors

Format

An object of class character of length 10.

Description

This function sequentially applies exclusion criteria to a data frame and counts the number of samples removed at each step.

Usage

exclusion_count(.df, ..., .criteria_names = NULL, .na_exclude = TRUE)

Arguments

Value

A data frame with two columns: 'Criteria' and 'N', showing the number of samples at the start, the number excluded at each step, and the final number remaining.

Examples

cohort <- data.frame(
  age = c(17, 25, 30, NA, 50, 60),
  sex = c("M", "F", "F", "M", "F", "M"),
  value = c(1, NA, 3, 4, 5, NA),
  dementia = c(TRUE, FALSE, FALSE, FALSE, TRUE, FALSE)
)
exclusion_count(
  cohort,
  age < 18,
  is.na(value),
  dementia == TRUE,
  .criteria_names = c(
    "Age < 18 years",
    "Missing value",
    "History of dementia"
  )
)

Description

Extract numerical values from strings. Can be used to filter out the unwanted information coming along with the numbers.

Usage

extract_num(
  x,
  res_type = c("first", "range"),
  multimatch2na = FALSE,
  leq_1 = FALSE,
  allow_neg = TRUE,
  zero_regexp = NULL,
  max_regexp = NULL,
  max_quantile = 0.95
)

Arguments

Details

The function uses regular expressions to extract numbers from strings. The regular expression used is "-?[0-9]+\\.?[0-9]*|-?\\.[0-9]+", which matches any number that may have a decimal point and may have a negative sign.

Value

A numeric vector.

Examples

x <- c("1.2(XXX)", "5-8POS", "NS", "FULL", "5.5", "4.2")
extract_num(x)
extract_num(x,
  res_type = "first", multimatch2na = TRUE, zero_regexp = "NEG|NS",
  max_regexp = "FULL"
)
extract_num(x, res_type = "range", allow_neg = FALSE, zero_regexp = "NEG|NS", max_regexp = "FULL")

Description

Fill NA values with the last valid value. Can be used to fill excel combined cells.

Usage

fill_with_last(x)

Arguments

Value

A vector.

Examples

fill_with_last(c(1, 2, NA, 4, NA, 6))

Description

Filter predictors that can be used to fit for RCS models.

Usage

filter_rcs_predictors(data, predictors = NULL)

Arguments

Value

A vector of predictor names. These variables are numeric and have more than 5 unique values.

Examples

filter_rcs_predictors(mtcars)

Description

Calculate the first mode of a vector. Ignore NA values. Can be used if any mode is acceptable.

Usage

first_mode(x, empty_return)

Arguments

Value

The first mode of the vector.

Examples

first_mode(c(1, 1, 2, 2, 3, 3, 3, NA, NA, NA))

Description

Format p-value with modified default settings suitable for publication.

Usage

format_pval(
  p,
  text_ahead = NULL,
  digits = 1,
  nsmall = 2,
  eps = 0.001,
  na_empty = TRUE
)

Arguments

Value

A string vector of formatted p values.

Examples

format_pval(c(0.001, 0.0001, 0.05, 0.1123456))
format_pval(c(0.001, 0.0001, 0.05, 0.1123456), text_ahead = "p value")

Description

Add covariates to a formula. Support both formula and character string.

Usage

formula_add_covs(formula, covars)

Arguments

Value

A formula.

Examples

formula_add_covs("y ~ a + b", c("c", "d"))

Description

Generate a string summary of a vector by picking samples.

Usage

get_samples(x, unique_only = FALSE, n_samples = 10, collapse = "\n")

Arguments

Value

A character string.

Examples

get_samples(c(1, 2, 3, 4, 5))
get_samples(c(1, 2, 3, 4, 5), n_samples = 2)
get_samples(c(1, 2, 3, 3, 3), n_samples = 2, unique_only = TRUE)
get_samples(c(1, 2, 3, 4, 5), collapse = ", ")

Description

Extract one valid (non-NA) value from a vector.

Usage

get_valid(x, mode = c("first", "mid", "last"), disjoint = FALSE)

Arguments

Value

A single valid value from the vector. NA if all values are invalid.

Examples

get_valid(c(NA, 1, 2, NA, 3, NA, 4))
get_valid(c(NA, 1, NA), mode = "last", disjoint = TRUE)

Description

Get the subset of a data frame that satisfies the missing rate condition using a greedy algorithm.

Usage

get_valid_subset(
  df,
  row_na_ratio = 0.5,
  col_na_ratio = 0.2,
  row_priority = 1,
  adaptive_scoring = FALSE,
  speedup_ratio = 0,
  return_index = FALSE
)

Arguments

Details

The function is based on a greedy algorithm. It iteratively removes the row or column with the highest excessive missing rate weighted by the inverse of row_priority until the missing rates of all rows and columns are below the specified threshold. Then it reversely tries to add rows and columns that do not break the conditions back and finalize the subset. The result depends on the row_priority parameter drastically, so it's recommended to try different row_priority values to find the most satisfying one.

When adaptive_scoring = TRUE, the scoring considers how much removing a row/column improves the missing rates of the other dimension. The score is calculated as:

• For rows: sum of improvements in column missing rates (how much closer columns get to col_na_ratio)

• For columns: sum of improvements in row missing rates (how much closer rows get to row_na_ratio) This allows the algorithm to consider removing rows/columns even if they don't exceed thresholds, if doing so helps other dimensions satisfy their thresholds.

Value

The subset data frame, or a list that contains the row and column indices of the subset.

Examples

data(cancer, package = "survival")
dim(cancer)
max_missing_rates(cancer)

cancer_valid <- get_valid_subset(cancer, row_na_ratio = 0.2, col_na_ratio = 0.1, row_priority = 1)
dim(cancer_valid)
max_missing_rates(cancer_valid)

Description

Automatic variable type and method determination for baseline table.

Usage

get_var_types(
  data,
  strata = NULL,
  norm_test_by_group = TRUE,
  omit_factor_above = 20,
  num_to_factor = 5,
  save_qqplots = FALSE,
  folder_name = "qqplots"
)

Arguments

Value

An object from class var_types, which is just list containing the following elements:

Note

This function performs normality tests on the variables in the data frame and determines whether they are normal. This is done by performing Shapiro-Wilk, Lilliefors, Anderson-Darling, Jarque-Bera, and Shapiro-Francia tests. If at least two of these tests indicate that the variable is nonnormal, then it is considered nonnormal. To alleviate the problem that normality tests become too sensitive when sample size gets larger, the alpha level is determined by an experience formula that decrease with sample size.

This function also marks the factor variables that require fisher exact tests if any cell haves expected frequency less than or equal to 5. Note that this criterion less strict than the commonly used one.

Examples

data(cancer, package = "survival")
get_var_types(cancer, strata = "sex") # set save_qqplots = TRUE to check the QQ plots

var_types <- get_var_types(cancer, strata = "sex")
# for some reason we want the variable "pat.karno" ro be considered normal.
var_types$nonnormal_vars <- setdiff(var_types$nonnormal_vars, "pat.karno")

Description

Creates an importance plot from a named vector of values.

Usage

importance_plot(
  x,
  x_lab = "Importance",
  top_n = NULL,
  color = c("#56B1F7", "#132B43"),
  show_legend = FALSE,
  split_at = NULL,
  show_labels = TRUE,
  digits = 2,
  nsmall = 3,
  scientific = TRUE,
  label_color = "black",
  label_size = 3,
  label_hjust = max(x)/10,
  save_plot = FALSE,
  filename = "importance.png"
)

Arguments

Details

The importance plot is a bar plot that shows the importance of each variable in a model. The variables are sorted in descending order of importance, and the top_n variables are shown. If top_n is NULL, all variables are shown. The plot can be split into two halves at a specified index, which is useful for illustrating variable selection.

Value

A ggplot object

Examples

set.seed(1)
dummy_importance <- runif(20)^5
names(dummy_importance) <- paste0("var", 1:20)
importance_plot(dummy_importance, top_n = 15, split_at = 10, save_plot = FALSE)

Description

If an element is duplicated, all of its occurrence will be labeled TRUE. Useful to list and compare all duplicates.

Usage

indicate_duplicates(x)

Arguments

Value

A logical vector.

Examples

indicate_duplicates(c(1, 2, NA, NA, 1))
indicate_duplicates(c(1, 2, 3, 4, 4))

# Useful to check duplicates in data frames.
df <- data.frame(
  id = c(1, 2, 1, 2, 3), year = c(2010, 2011, 2010, 2010, 2011),
  value = c(1, 2, 3, 4, 5)
)
df[indicate_duplicates(df[, c("id", "year")]), ]

Description

This function calculates the interaction p-value between a predictor and a group variable in a linear, logistic, or Cox proportional hazards model.

Usage

interaction_p_value(
  data,
  y,
  predictor,
  group_var,
  time = NULL,
  time2 = NULL,
  covars = NULL,
  cluster = NULL,
  rcs_knots = NULL
)

Arguments

Value

A numerical, the interaction p-value

Examples

data(cancer, package = "survival")
interaction_p_value(
  data = cancer, y = "status", predictor = "age", group_var = "sex",
  time = "time", rcs_knots = 4
)

Description

Plot interactions between variables. Both logistic and Cox proportional hazards regression models are supported. The predictor variables in the model are can be used both in linear form or in restricted cubic spline form.

Usage

interaction_plot(
  data,
  y,
  predictor,
  group_var,
  time = NULL,
  time2 = NULL,
  covars = NULL,
  cluster = NULL,
  group_colors = NULL,
  save_plot = FALSE,
  filename = NULL,
  height = 4,
  width = 4,
  xlab = predictor,
  ylab = NULL,
  show_n = TRUE,
  group_title = group_var,
  ...
)

Arguments

Value

A ggplot object.

Examples

data(cancer, package = "survival")
interaction_plot(cancer,
  y = "status", time = "time", predictor = "age", group_var = "sex",
  save_plot = FALSE
)
interaction_plot(cancer,
  y = "status", predictor = "age", group_var = "sex",
  save_plot = FALSE
)
interaction_plot(cancer,
  y = "wt.loss", predictor = "age", group_var = "sex",
  save_plot = FALSE
)

Description

Scan for interactions between variables and output results. Both logistic and Cox proportional hazards regression models are supported. The predictor variables in the model are can be used both in linear form or in restricted cubic spline form.

Usage

interaction_scan(
  data,
  y,
  time = NULL,
  time2 = NULL,
  predictors = NULL,
  group_vars = NULL,
  covars = NULL,
  cluster = NULL,
  try_rcs = TRUE,
  p_adjust_method = "BH",
  save_table = FALSE,
  filename = NULL
)

Arguments

Value

A data frame containing the results of the interaction analysis.

Examples

data(cancer, package = "survival")
interaction_scan(cancer, y = "status", time = "time", save_table = FALSE)

Description

Desensitize a character vector by removing the unneeded part of each string. The retained part is determined by keyword matches from a regular expression.

Usage

keep_by_keyword(
  x,
  keyword,
  from = c("start", "first", "last"),
  to = c("first", "last", "end"),
  include_keyword = TRUE
)

Arguments

Value

A character vector with retained text only.

Examples

urls <- c(
  "https://hospital.example.com/patient/123?token=abc",
  "https://trial.example.org/visit/456"
)
# Keep domain only
keep_by_keyword(urls, "com|org|net", from = "start", to = "last", include_keyword = TRUE)

ids <- c("SITE-2026-0001", "CTR-2025-0912")
# Keep site prefix before first '-'
keep_by_keyword(ids, "-", from = "start", to = "first", include_keyword = FALSE)

Description

Mark possible outliers in a numeric vector using various methods. These functions return a logical vector indicating which values are outliers.

Usage

mad_outlier(x, threshold = 1.4826 * 3)

iqr_outlier(x, threshold = 1.5)

zscore_outlier(x, threshold = 3)

Arguments

Details

• MAD method: Uses median absolute deviation to identify outliers. Values with absolute deviation from the median greater than the threshold are considered outliers.

• IQR method: Uses interquartile range to identify outliers. Values below Q1 - threshold * IQR or above Q3 + threshold * IQR are considered outliers.

• Z-score method: Uses standardized Z-scores to identify outliers. Values with an absolute Z-score greater than the threshold are considered outliers.

Value

A logical vector indicating which values are outliers.

Examples

x <- c(1, 2, 3, 4, 5, 100, NA)
mad_outlier(x)
iqr_outlier(x, threshold = 2.0)
zscore_outlier(x, threshold = 2.5)

Description

Get the maximum missing rate of rows and columns.

Usage

max_missing_rates(df)

Arguments

Value

A list that contains the maximum missing rate of rows and columns.

Examples

data(cancer, package = "survival")
max_missing_rates(cancer)

Description

Merge two data frames where shared keys in by must match exactly and the value in y[[y_val]] must fall within the range defined by x[[x_start]] and x[[x_end]].

This function is particularly useful for date-based matching scenarios, where you need to match events (e.g., examinations, treatments) to time intervals (e.g., hospital admissions, visits). While the function accepts any ordered values (numeric, Date, POSIXt), date matching is the primary use case.

This avoids constructing the full Cartesian product that would be produced by a regular equality join followed by range filtering.

Merge two data frames where shared keys in by must match exactly and the value in y[[y_val]] must fall within the range defined by x[[x_start]] and x[[x_end]].

This function is particularly useful for date-based matching scenarios, where you need to match events (e.g., examinations, treatments) to time intervals (e.g., hospital admissions, visits). While the function accepts any ordered values (numeric, Date, POSIXt), date matching is the primary use case.

This avoids constructing the full Cartesian product that would be produced by a regular equality join followed by range filtering.

Usage

merge_by_range(
  x,
  y,
  by,
  x_start,
  x_end = NULL,
  y_val,
  range_relax = c(0, 0),
  all_y = TRUE,
  suffixes = c(".x", ".y")
)

merge_by_range(
  x,
  y,
  by,
  x_start,
  x_end = NULL,
  y_val,
  range_relax = c(0, 0),
  all_y = TRUE,
  suffixes = c(".x", ".y")
)

Arguments

Details

Matching proceeds in three stages:

1. Rows in x and y are first grouped by the exact-match keys in by.

2. Within each group, y[[y_val]] is matched against the interval defined by x[[x_start]] and x[[x_end]], optionally extended by range_relax.

3. When range_relax is non-zero, the relaxed intervals are clipped against neighboring core intervals before matching, but never clipped further than the original core interval.

If any row from y still matches multiple clipped ranges in x, a warning is issued and .cp_y_row_id is retained in the output so duplicate matches can be identified downstream.

When all_y = TRUE, rows from y with no match are appended to the result with NA values for columns coming from x and for since_start.

Matching proceeds in three stages:

1. Rows in x and y are first grouped by the exact-match keys in by.

2. Within each group, y[[y_val]] is matched against the interval defined by x[[x_start]] and x[[x_end]], optionally extended by range_relax.

3. When range_relax is non-zero, the relaxed intervals are clipped against neighboring core intervals before matching, but never clipped further than the original core interval.

If any row from y still matches multiple clipped ranges in x, a warning is issued and .cp_y_row_id is retained in the output so duplicate matches can be identified downstream.

When all_y = TRUE, rows from y with no match are appended to the result with NA values for columns coming from x and for since_start.

Value

A data frame containing matched rows from x and y. The output includes a since_start column indicating the numeric difference between y_val and x_start (in the units of the values, e.g., days for Date objects).

A data frame containing matched rows from x and y. The output includes a since_start column indicating the numeric difference between y_val and x_start (in the units of the values, e.g., days for Date objects).

Examples

admissions <- data.frame(
  patient_id = c(1, 1, 2),
  date_start = as.Date(c("2024-01-01", "2024-02-01", "2024-03-01")),
  date_end = as.Date(c("2024-01-10", "2024-02-10", "2024-03-05")),
  ward = c("A", "B", "C")
)
examinations <- data.frame(
  patient_id = c(1, 1, 2, 3),
  exam_date = as.Date(c("2024-01-05", "2024-02-10", "2024-03-07", "2024-01-01")),
  exam_name = c("CT", "MRI", "XR", "US")
)

merge_by_range(
  x = admissions,
  y = examinations,
  by = "patient_id",
  x_start = "date_start",
  x_end = "date_end",
  y_val = "exam_date"
)

admissions <- data.frame(
  patient_id = c(1, 1, 2),
  date_start = as.Date(c("2024-01-01", "2024-02-01", "2024-03-01")),
  date_end = as.Date(c("2024-01-10", "2024-02-10", "2024-03-05")),
  ward = c("A", "B", "C")
)
examinations <- data.frame(
  patient_id = c(1, 1, 2, 3),
  exam_date = as.Date(c("2024-01-05", "2024-02-10", "2024-03-07", "2024-01-01")),
  exam_name = c("CT", "MRI", "XR", "US")
)

merge_by_range(
  x = admissions,
  y = examinations,
  by = "patient_id",
  x_start = "date_start",
  x_end = "date_end",
  y_val = "exam_date"
)

Description

This function merges two data frames based on string key matching. It searches for keys from key_df[[key_col]] in data[[search_col]] and adds corresponding columns from key_df to data.

Usage

merge_by_substring(
  data,
  key_df,
  search_col,
  key_col,
  value_cols,
  case_insensitive = TRUE,
  ...
)

Arguments

Value

A data frame with all columns from data plus matched columns from key_df. Unmatched rows will have NA values in the added columns.

Examples

# Basic usage
main_data <- data.frame(
  name = c("AB", "B,C", "A..", "ACD"),
  value = c(1, 2, 3, 4)
)
key_lookup <- data.frame(
  key = c("A", "B", "C", "ACD", "AB"),
  category = c("cat1", "cat2", "cat3", "cat4", "cat1"),
  code = c("001", "002", "003", "004", "001")
)
result <- merge_by_substring(main_data, key_lookup,
  search_col = "name",
  key_col = "key", value_cols = c("category", "code")
)
print(result)

Description

Merge multiple vectors into one while trying to maintain the order of elements in each vector. The relative order of elements is compared by their first occurrence in the vectors in the list. This function is useful when merging slightly different vectors, such as questionnaires of different versions.

Usage

merge_ordered_vectors(vectors)

Arguments

Value

A vector.

Examples

merge_ordered_vectors(list(c(1, 3, 4, 5, 7, 10), c(2, 5, 6, 7, 8), c(1, 7, 5, 10)))

Description

Instead of returning -Inf or Inf, returns NA if all values are NA. It also ignores NA values by default, which is different from base R functions. This is useful when summarizing data frames with dplyr::summarise().

Usage

na_max(x, na.rm = TRUE)

na_min(x, na.rm = TRUE)

Arguments

Value

The minimum or maximum value of the vector or NA if all values are NA.

Examples

na_max(c(1, 2, 3, NA))
na_min(c(NA, NA, NA))

Description

Replace NA values with FALSE in logical vectors. For other vectors, the behavior relies on R's automatic conversion rules.

Usage

na2false(x)

Arguments

Value

A vector with NA values replaced by FALSE.

Examples

na2false(c(TRUE, FALSE, NA, TRUE, NA))
na2false(c(1, 2, NA))

Description

This is a versatile function to plot the relationship between a predictor variable and the outcome. It supports numeric (linear or RCS) and categorical predictors for logistic, linear, and Cox models. It can display the distribution of the predictor variable as a histogram (for numeric) or bar plot (for categorical).

Usage

predictor_effect_plot(
  data,
  x,
  y,
  time = NULL,
  time2 = NULL,
  covars = NULL,
  cluster = NULL,
  method = "auto",
  knot = 4,
  add_hist = TRUE,
  ref = "x_median",
  ref_digits = 3,
  show_total_n = TRUE,
  group_by_ref = TRUE,
  group_title = NULL,
  group_labels = NULL,
  group_colors = NULL,
  breaks = 20,
  line_color = "#e23e57",
  print_p_ph = TRUE,
  trans = "identity",
  save_plot = FALSE,
  create_dir = FALSE,
  filename = NULL,
  y_lim = NULL,
  hist_max = NULL,
  xlim = NULL,
  height = 6,
  width = 6,
  return_details = FALSE
)

Arguments

Value

A ggplot object, or a list with the plot and details if return_details is TRUE.

Examples

data(cancer, package = "survival")
cancer$dead <- cancer$status == 2
cancer <- cancer[!is.na(cancer$inst), ]
predictor_effect_plot(
  data = cancer,
  x = "age",
  y = "dead",
  method = "linear",
  covars = "ph.karno",
  add_hist = FALSE,
  trans = "log2",
  save_plot = FALSE,
  cluster = "inst"
)

Description

QQ plot for a sample.

Usage

qq_show(
  x,
  title = NULL,
  save = FALSE,
  filename = "QQplot.png",
  width = 2,
  height = 2
)

Arguments

Value

A plot.

Examples

qq_show(rnorm(100))

Description

This function is a wrapper for predictor_effect_plot with method = "rcs". It plots a restricted cubic spline for a predictor in a regression model.

Usage

rcs_plot(
  data,
  x,
  y,
  time = NULL,
  time2 = NULL,
  covars = NULL,
  cluster = NULL,
  knot = 4,
  add_hist = TRUE,
  ref = "x_median",
  ref_digits = 3,
  show_total_n = TRUE,
  group_by_ref = TRUE,
  group_title = NULL,
  group_labels = NULL,
  group_colors = NULL,
  breaks = 20,
  rcs_color = "#e23e57",
  print_p_ph = TRUE,
  trans = "identity",
  save_plot = FALSE,
  create_dir = FALSE,
  filename = NULL,
  y_lim = NULL,
  hist_max = NULL,
  xlim = NULL,
  height = 6,
  width = 6,
  return_details = FALSE
)

Arguments

Value

A ggplot object, or a list containing the ggplot object and other details if return_details is TRUE.

Examples

data(cancer, package = "survival")
# coxph model with time assigned
rcs_plot(cancer, x = "age", y = "status", time = "time", covars = "ph.karno", save_plot = FALSE)

# logistic model with time not assigned
cancer$dead <- cancer$status == 2
rcs_plot(cancer, x = "age", y = "dead", covars = "ph.karno", save_plot = FALSE)

Description

Generate the result table of logistic or Cox regression with different settings of the predictor variable and covariates. Also generate KM curves for Cox regression.

Usage

regression_basic_results(
  data,
  x,
  y,
  time = NULL,
  time2 = NULL,
  model_covs = NULL,
  cluster = NULL,
  pers = c(0.1, 10, 100),
  factor_breaks = NULL,
  factor_labels = NULL,
  quantile_breaks = NULL,
  quantile_labels = NULL,
  label_with_range = FALSE,
  save_output = FALSE,
  figure_type = "png",
  ref_levels = "lowest",
  est_nsmall = 2,
  p_nsmall = 3,
  pval_eps = 0.001,
  median_nsmall = 0,
  colors = NULL,
  xlab = NULL,
  legend_title = x,
  legend_pos = c(0.8, 0.8),
  pval_pos = NULL,
  n_y_pos = 0.9,
  height = 6,
  width = 6,
  ...
)

Arguments

Details

The function regression_basic_results generates the result table of logistic or Cox regression with different settings of the predictor variable and covariates. The setting of the predictor variable includes the original x, the standardized x, the log of x, and x divided by denominators in pers as continuous variables, and the factorization of the variable including split by median, by quartiles, and by factor_breaks and quantile_breaks. The setting of the covariates includes different models with different covariates.

Value

A list of results, including the regression table and the KM curve plots.

Note

For factor variables with more than 2 levels, p value for trend is also calculated.

Examples

data(cancer, package = "survival")
# coxph model with time assigned
regression_basic_results(cancer,
  x = "age", y = "status", time = "time",
  model_covs = list(Crude = c(), Model1 = c("ph.karno"), Model2 = c("ph.karno", "sex")),
  save_output = FALSE,
  ggtheme = survminer::theme_survminer(font.legend = c(14, "plain", "black")) # theme for KM
)

# logistic model with time not assigned
cancer$dead <- cancer$status == 2
regression_basic_results(cancer,
  x = "age", y = "dead", ref_levels = c("Q3", "High"),
  model_covs = list(Crude = c(), Model1 = c("ph.karno"), Model2 = c("ph.karno", "sex")),
  save_output = FALSE
)

Description

This function fit the regression of a predictor in a linear, logistic, or Cox proportional hazards model.

Usage

regression_fit(
  data,
  y,
  predictor,
  time = NULL,
  time2 = NULL,
  covars = NULL,
  cluster = NULL,
  rcs_knots = NULL,
  returned = c("full", "predictor_split", "predictor_combined")
)

Arguments

Value

A list containing the regression ratio and p-value of the predictor. If rcs_knots is not NULL, the list contains the overall p-value and the nonlinear p-value of the rcs model. If return_full_result is TRUE, the complete result of the regression model is returned.

Examples

data(cancer, package = "survival")
regression_fit(data = cancer, y = "status", predictor = "age", time = "time", rcs_knots = 4)

Description

Generate the forest plot of logistic or Cox regression with different models.

Usage

regression_forest(
  data,
  model_vars,
  y,
  time = NULL,
  time2 = NULL,
  cluster = NULL,
  as_univariate = FALSE,
  est_nsmall = 2,
  p_nsmall = 3,
  show_vars = NULL,
  save_plot = FALSE,
  filename = NULL,
  ...
)

Arguments

Value

A gtable object.

Examples

data(cancer, package = "survival")
cancer$ph.ecog_cat <- factor(cancer$ph.ecog, levels = c(0:3), labels = c("0", "1", ">=2", ">=2"))
regression_forest(cancer,
  model_vars = c("age", "sex", "wt.loss", "ph.ecog_cat", "meal.cal"), y = "status", time = "time",
  as_univariate = TRUE, save_plot = FALSE
)

regression_forest(cancer,
  model_vars = c("age", "sex", "wt.loss", "ph.ecog_cat", "meal.cal"), y = "status", time = "time",
  show_vars = c("age", "sex", "ph.ecog_cat", "meal.cal"), save_plot = FALSE
)

regression_forest(cancer,
  model_vars = list(
    M0 = c("age"),
    M1 = c("age", "sex", "wt.loss", "ph.ecog_cat", "meal.cal"),
    M2 = c("age", "sex", "wt.loss", "ph.ecog_cat", "meal.cal", "pat.karno")
  ),
  y = "status", time = "time",
  show_vars = c("age", "sex", "ph.ecog_cat", "meal.cal"), save_plot = FALSE
)

Description

Scan for significant regression predictors and output results. Both logistic and Cox proportional hazards regression models are supported. The predictor variables in the model are can be used both in linear form or in restricted cubic spline form.

Usage

regression_scan(
  data,
  y,
  time = NULL,
  time2 = NULL,
  predictors = NULL,
  covars = NULL,
  cluster = NULL,
  num_to_factor = 5,
  p_adjust_method = "BH",
  save_table = FALSE,
  filename = NULL
)

Arguments

Details

The function first determines the type of each predictor variable (numerical, factor, num_factor (numerical but with less unique values than or equal to num_to_factor), or other). Then, it performs regression analysis for available transforms of each predictor variable and saves the results.

Value

A data frame containing the results of the regression analysis.

The available transforms for each predictor type are

• numerical: original, logarithm, categorized, rcs

• num_factor: original, categorized

• factor: original

• other: none

The transforms are applied as follows

• original: Fit the regression model with the original variable. Provide HR/OR and p-values in results.

• logarithm: If the numerical variable is all greater than 0, fit the regression model with the log-transformed variable. Provide HR/OR and p-values in results.

• categorized: For numerical variables, fit the regression model with the binarized variable split at the median value. For num_factor variables, fit the regression model with the variable after as.factor(). Provide HR/OR and p-values in results. If the number of levels is greater than 2, no single HR/OR is provided, but the p-value of the overall test can be provided with TYPE-2 ANOVA from car::Anova().

• rcs: Fit the regression model with the restricted cubic spline variable. The overall and nonlinear p-values are provided in results. These p-vals are calculated by anova() of rms::cph() or rms::Glm.

Examples

data(cancer, package = "survival")
regression_scan(cancer, y = "status", time = "time", save_table = FALSE)

Description

Replacing elements in a vector

Usage

replace_elements(x, from, to)

Arguments

Value

A vector.

Examples

replace_elements(c("a", "x", "1", NA, "a"), c("a", "b", NA), c("A", "B", "XX"))

Description

One-call cohort screening pipeline with expression stages:

1. entry stage: evaluate entry_expr and decide which keys enter downstream;

2. anchor stage (optional): evaluate anchor_expr and keep records from first anchor onward;

3. optional follow-up visit filtering;

4. optional outer-join integration.

entry_expr and anchor_expr support boolean combinations of grouped terms, for example: any(Hb > 10) & all(icd != "J18") or mean(Hb, na.rm = TRUE) > 10 & any(icd == "I10"). & is applied as set intersection and | as set union on keys defined by level.

Usage

screen_data_list(
  data_list,
  entry_expr,
  entry_level = c("patient_id", "visit_id", "date"),
  anchor_expr = NULL,
  anchor_level = c("date", "visit_id"),
  anchor_window = c("from_first_anchor", "none"),
  patient_id_map,
  visit_id_map = NULL,
  date_map = NULL,
  followup_min_visits = NULL,
  followup_table = NULL,
  output = c("list", "joined"),
  return_audit = FALSE,
  verbose = FALSE
)

Arguments

Value

If return_audit = FALSE, returns filtered list or joined data frame. If return_audit = TRUE, returns a list with:

• data: filtered list or joined data frame

• audit$entry_scope: entry key scope application log

• audit$anchor_scope: anchor window application log

• audit$followup: follow-up filtering log

• audit$join: join step log

Examples

patient <- data.frame(pid = 1:3)
admission <- data.frame(
  pid = c(1, 1, 2, 2, 3),
  vid = c(11, 12, 21, 22, 31),
  admit_day = c(1, 5, 2, 8, 3)
)
diagnosis <- data.frame(
  pid = c(1, 1, 2, 3),
  vid = c(11, 12, 21, 31),
  dx_day = c(1, 5, 2, 3),
  icd = c("I10", "I11", "I10", "J18")
)
lab <- data.frame(
  pid = c(1, 1, 2, 2, 3),
  vid = c(11, 12, 21, 22, 31),
  lab_day = c(1, 5, 2, 8, 3),
  Hb = c(9.8, 11.3, 10.8, 9.2, 8.6)
)

# Scenario 1: any target diagnosis, keep all records of matched patients.
res_s1 <- screen_data_list(
  data_list = list(patient = patient, admission = admission, diagnosis = diagnosis, lab = lab),
  entry_expr = any(icd == "I10"),
  entry_level = "patient_id",
  patient_id_map = "pid",
  output = "list"
)

# Scenario 2: any target diagnosis, keep diagnosis-index admission and after.
res_s2 <- screen_data_list(
  data_list = list(patient = patient, admission = admission, diagnosis = diagnosis, lab = lab),
  entry_expr = any(icd == "I10"),
  entry_level = "patient_id",
  anchor_expr = icd == "I10",
  anchor_level = "date",
  anchor_window = "from_first_anchor",
  patient_id_map = "pid",
  visit_id_map = c(admission = "vid", diagnosis = "vid", lab = "vid"),
  date_map = c(admission = "admit_day", diagnosis = "dx_day", lab = "lab_day"),
  output = "list"
)

# Scenario 3: target diagnosis patients, then abnormal indicator visit and after.
res_s3 <- screen_data_list(
  data_list = list(patient = patient, admission = admission, diagnosis = diagnosis, lab = lab),
  entry_expr = any(icd == "I10"),
  entry_level = "patient_id",
  anchor_expr = Hb > 10,
  anchor_level = "date",
  anchor_window = "from_first_anchor",
  patient_id_map = "pid",
  visit_id_map = c(admission = "vid", diagnosis = "vid", lab = "vid"),
  date_map = c(admission = "admit_day", diagnosis = "dx_day", lab = "lab_day"),
  output = "list"
)

Description

Split multi-choice data into columns, each new column consists of booleans whether a choice is presented.

Usage

split_multichoice(
  df,
  quest_cols,
  split = "",
  remove_space = TRUE,
  link = "_",
  remove_cols = TRUE
)

Arguments

Value

A data frame with additional columns.

Examples

df <- data.frame(q1 = c("ab", "c da", "b a", NA), q2 = c("a b", "a c", "d", "ab"))
split_multichoice(df, quest_cols = c("q1", "q2"))

Description

Partially match a string and replace with corresponding value. This function is useful to recover the original names of variables after legalized using make.names or modified by other functions.

Usage

str_match_replace(x, to_match, to_replace)

Arguments

Value

A vector.

Examples

ori_names <- c("xx (mg/dl)", "b*x", "Covid-19")
modified_names <- c("v1", "v2", "v3")
x <- c("v1.v2", "v3.yy", "v4")
str_match_replace(x, modified_names, ori_names)

Description

Create subgroup forest plot with glm or coxph models. The interaction p-values are calculated using likelihood ratio tests.

Usage

subgroup_forest(
  data,
  subgroup_vars,
  x,
  y,
  time = NULL,
  time2 = NULL,
  standardize_x = FALSE,
  covars = NULL,
  cluster = NULL,
  est_nsmall = 2,
  p_nsmall = 3,
  group_cut_quantiles = 0.5,
  save_plot = FALSE,
  filename = NULL,
  ...
)

Arguments

Value

A gtable object.

Examples

data(cancer, package = "survival")
# coxph model with time assigned
subgroup_forest(cancer,
  subgroup_vars = c("age", "sex", "wt.loss"), x = "ph.ecog", y = "status",
  time = "time", covars = "ph.karno", ticks_at = c(1, 2), save_plot = FALSE
)

# logistic model with time not assigned
cancer$dead <- cancer$status == 2
subgroup_forest(cancer,
  subgroup_vars = c("age", "sex", "wt.loss"), x = "ph.ecog", y = "dead",
  covars = "ph.karno", ticks_at = c(1, 2), save_plot = FALSE
)

cancer$ph.ecog_cat <- factor(cancer$ph.ecog, levels = c(0:3), labels = c("0", "1", ">=2", ">=2"))
subgroup_forest(cancer,
  subgroup_vars = c("sex", "wt.loss"), x = "ph.ecog_cat", y = "dead",
  covars = "ph.karno", ticks_at = c(1, 2), save_plot = FALSE
)

Description

Get a table of subject details for the clinical data. This table could be labeled and used for subject name standardization.

Usage

subject_view(
  df,
  subject_col,
  info_cols,
  value_col = NULL,
  info_n_samples = 10,
  info_collapse = "\n",
  info_unique = FALSE,
  save_table = FALSE,
  filename = NULL
)

Arguments

Value

A data frame of subject details.

Examples

df <- data.frame(subject = sample(c("a", "b"), 1000, replace = TRUE), value = runif(1000))
df$unit <- NA
df$unit[df$subject == "a"] <- sample(c("mg/L", "g/l", "g/L"),
  sum(df$subject == "a"),
  replace = TRUE
)
df$value[df$subject == "a" & df$unit == "mg/L"] <-
  df$value[df$subject == "a" & df$unit == "mg/L"] * 1000
df$unit[df$subject == "b"] <- sample(c(NA, "g", "mg"), sum(df$subject == "b"), replace = TRUE)
df$value[df$subject == "b" & df$unit %in% "mg"] <-
  df$value[df$subject == "b" & df$unit %in% "mg"] * 1000
df$value[df$subject == "b" & is.na(df$unit)] <- df$value[df$subject == "b" & is.na(df$unit)] *
  sample(c(1, 1000), size = sum(df$subject == "b" & is.na(df$unit)), replace = TRUE)
subject_view(
  df = df, subject_col = "subject", info_cols = c("value", "unit"), value_col = "value",
  save_table = FALSE
)

Description

Perform multiple normality tests on a numeric variable and determine if it follows normal distribution.

Usage

test_normality(x, alpha = 0.05, all_positive = NULL)

Arguments

Value

A logical value indicating whether the variable is normal (TRUE) or non-normal (FALSE).

Note

This function performs Shapiro-Wilk, Lilliefors, Anderson-Darling, Jarque-Bera, and Shapiro-Francia tests. If at least two of these tests indicate that the variable is nonnormal (p < alpha), then it is considered nonnormal. For positive variables, if SD < mean, it's also considered non-normal as it suggests right skewness.

Examples

# Test normal data
normal_data <- rnorm(100)
test_normality(normal_data)

# Test non-normal data
skewed_data <- rexp(100)
test_normality(skewed_data)

Description

Calculate time-dependent ROC curves using the timeROC package and plot them using ggplot2.

Usage

time_roc_plot(
  data,
  time_var,
  event_var,
  marker_var,
  times = c(12, 36, 60),
  time_unit = "months",
  weighting = "marginal",
  cause = 1,
  colors = NULL,
  title = FALSE,
  save_plot = FALSE,
  filename = "time_roc.png"
)

Arguments

Value

A list containing:

• time_roc: The timeROC result object.

• plot: A ggplot object of the time-dependent ROC curves.

Examples

# Plot time-dependent ROC curves using lung dataset from survival package
library(survival)
data(cancer, package = "survival")
# Use age as the marker variable, plot at 180, 365, and 730 days
lung$status <- lung$status == 2
result <- time_roc_plot(lung, "time", "status", "age", times = c(180, 365, 730), time_unit = "days")
result$plot

# Save the plot to a file
# time_roc_plot(lung, "time", "status", "age", times = c(180, 365, 730), 
#               time_unit = "days", save_plot = TRUE)

Description

Convert numerical (especially Excel date) or character date to date. Can deal with common formats and allow different formats in one vector.

Usage

to_date(
  x,
  from_excel = TRUE,
  verbose = TRUE,
  try_formats = c("%Y-%m-%d", "%Y/%m/%d", "%Y%m%d", "%Y.%m.%d")
)

Arguments

Value

A single valid value from the vector. NA if all values are invalid.

Examples

to_date(c(43562, "2020-01-01", "2020/01/01", "20200101", "2020.01.01"))

Description

Convert long-format data to wide format by grouping keys, using one column as item names and one column as values. When there are multiple values under the same key-item combination, values are reduced by agg_fun. Designed to convert long-format clinical data in database to wide format for analysis and publication.

Usage

to_wide(df, keys, item_col, value_col, items = NULL, agg_fun = get_valid)

Arguments

Value

A wide-format data frame.

Examples

df <- data.frame(
  id = c(1, 1, 1, 2, 2),
  visit = c("v1", "v1", "v1", "v1", "v1"),
  item = c("A", "A", "B", "A", "C"),
  value = c(3, 5, 2, 1, 9)
)

to_wide(
  df,
  keys = c("id", "visit"),
  item_col = "item",
  value_col = "value",
  items = c("A", "B", "C"),
  agg_fun = max
)