Package 'AURMC' reference manual

Title:	Area Under the Repeated Measures Curve
Description:	Estimates and compares areas under curves formed by repeatedly measured outcomes observed subject to censoring and a terminal event. Implements Kaplan-Meier adjustment for censoring, influence-function standard errors, Wald inference, and multiplier perturbation inference, with utilities for interpolation, simulation, tabulation, and plotting. For additional details, see: McCaw ZR, Armbruster S, Tian L, Claggett BL, Fitzmaurice G, Foà A, Pfeffer MA, Wei LJ (2026) <doi:10.1016/j.jchf.2026.103013>.
Authors:	Zachary McCaw [aut, cre] (ORCID: <https://orcid.org/0000-0002-2006-9828>)
Maintainer:	Zachary McCaw <[email protected]>
License:	GPL-3
Version:	0.5.0
Built:	2026-10-28 19:15:00 UTC
Source:	https://github.com/cran/AURMC

Tabulate At-Risk Matrix R

Description

Construct a subject (row) by evaluation time (col) matrix.

Usage

AtRiskMatrixR(eval_times, idx, time)
AtRiskMatrixR(eval_times, idx, time)

Arguments

eval_times

Evaluation times.

idx

Unique subject index.

time

Observation time.

Value

Numeric matrix.

Area Under the Repeated Measures Curve

Description

Area Under the Repeated Measures Curve

Usage

AURMC(
  data,
  alpha = 0.05,
  censor_after_last = TRUE,
  idx_name = "idx",
  int_method = "trapezoid",
  perturbations = NULL,
  random_state = 0,
  status_name = "status",
  tau = NULL,
  time_name = "time",
  value_name = "value"
)
AURMC(
  data,
  alpha = 0.05,
  censor_after_last = TRUE,
  idx_name = "idx",
  int_method = "trapezoid",
  perturbations = NULL,
  random_state = 0,
  status_name = "status",
  tau = NULL,
  time_name = "time",
  value_name = "value"
)

Arguments

data

Data.frame.

alpha

Type I error.

censor_after_last

Introduce censoring after the last event if no observation-terminating event is present.

idx_name

Name of column containing a unique subject index.

int_method

Integration method, selected from "left", "right", "trapezoid".

perturbations

Number of perturbations to use for bootstrap inference. If NULL, only analytical inference is performed.

random_state

Seed to ensure perturbations are reproducible.

status_name

Name of column containing the status. Must be coded as 0 for censoring, 1 for a measurement, 2 for death. Each subject should have an observation-terminating event, either censoring or death.

tau

Truncation time.

time_name

Name of column containing the observation time.

value_name

Name of the column containing the measurement.

Value

A data.frame containing the method, truncation time, area estimate, standard error, confidence limits, and p-value.

Examples

example_data <- data.frame(
  idx = rep(1:3, each = 2),
  time = rep(c(0, 1), 3),
  status = rep(c(1, 0), 3),
  value = c(1, 1, 2, 2, 3, 3)
)
AURMC(example_data, tau = 1)
example_data <- data.frame(
  idx = rep(1:3, each = 2),
  time = rep(c(0, 1), 3),
  status = rep(c(1, 0), 3),
  value = c(1, 1, 2, 2, 3, 3)
)
AURMC(example_data, tau = 1)

AURMC Object

Description

AURMC Object

Slots

Arm0: Results for the reference arm.
Arm1: Results for the treatment arm.
Contrast: Contrasts.

Bootstrap Samples R

Description

Returns a bootstrap (row) by statistic (col) matrix. If return_auc = TRUE, the output has a single column, the AUC. If return_auc = FALSE, the output has a single column for each evaluation time.

Usage

BootstrapSamplesR(
  boot,
  eval_times,
  idx,
  status,
  time,
  value,
  int_method = "trapezoid",
  replace_na = FALSE,
  return_auc = FALSE,
  trunc_time = NULL
)
BootstrapSamplesR(
  boot,
  eval_times,
  idx,
  status,
  time,
  value,
  int_method = "trapezoid",
  replace_na = FALSE,
  return_auc = FALSE,
  trunc_time = NULL
)

Arguments

boot

Bootstrap replicates.

eval_times

Evaluation times.

idx

Unique subject index.

status

Status, coded as 0 for censoring, 1 for a measurement, 2 for a terminal event.

time

Observation time.

value

Observation value.

int_method

Integration method, selected from "left", "right", "trapezoid".

replace_na

Replace NaN with zero?

return_auc

Return the AUC?

trunc_time

Truncation time? Optional. If omitted, defaults to the maximum evaluation time.

Value

Numeric matrix.

Calculate Martingale

Description

Calculate $dM_{i}(t) = dN_{i}(t) - Y_{i}(t)d\Lambda(t)$ .

Usage

CalcMartingaleR(haz, idx, status, time, unique_times)
CalcMartingaleR(haz, idx, status, time, unique_times)

Arguments

haz

Value of the hazard at each unique time.

idx

Subject index.

status

Status, coded as 0 for censoring, 1 for a measurement, 2 for a terminal event.

time

Subject observation times.

unique_times

Unique times at which to obtain the martingale.

Value

Matrix with subjects as rows and unique times as columns.

Evaluate the quadrature tail associated with $\mu(t; \tau) = \int_{t}^{\tau}{S(u-)d(u)/y(u)}du$ . The current grid point is excluded because the hazard jump at $t$ affects $\hat S(u-)$ only for $u > t$ .

Usage

CalcMuR(d, surv, unique_times, y, int_method = "trapezoid")
CalcMuR(d, surv, unique_times, y, int_method = "trapezoid")

Arguments

d

Value of d(t) at each time point.

surv

Value of $S(t-)$ at each time point.

unique_times

Unique values of time t.

y

Value of y(t) at each time point.

int_method

Integration method, selected from "left", "right", "trapezoid".

Value

Numeric vector of $\mu(t; tau)$ .

Censor After Last

Description

Introduce a censoring after the last event if no observation terminating event is present.

Usage

CensorAfterLast(data)
CensorAfterLast(data)

Arguments

data

Data.frame.

Value

None.

Compare Areas Under Repeated Measures Curves

Description

Compare Areas Under Repeated Measures Curves

Usage

CompareAURMCs(
  data,
  alpha = 0.05,
  arm_name = "arm",
  censor_after_last = TRUE,
  idx_name = "idx",
  int_method = "trapezoid",
  perturbations = NULL,
  random_state = 0,
  status_name = "status",
  tau = NULL,
  time_name = "time",
  value_name = "value"
)
CompareAURMCs(
  data,
  alpha = 0.05,
  arm_name = "arm",
  censor_after_last = TRUE,
  idx_name = "idx",
  int_method = "trapezoid",
  perturbations = NULL,
  random_state = 0,
  status_name = "status",
  tau = NULL,
  time_name = "time",
  value_name = "value"
)

Arguments

data

Data.frame.

alpha

Type I error.

arm_name

Name of the column containing treatment arm. Coded as 0 for reference, 1 for treatment.

censor_after_last

Introduce censoring after the last event if no observation-terminating event is present.

idx_name

Name of column containing a unique subject index.

int_method

Integration method, selected from "left", "right", "trapezoid".

perturbations

Number of perturbations to use for bootstrap inference. If NULL, only analytical inference is performed.

random_state

Seed to ensure perturbations are reproducible.

status_name

Name of column containing the status. Must be coded as 0 for censoring, 1 for a measurement, 2 for death. Each subject should have an observation-terminating event, either censoring or death.

tau

Truncation time.

time_name

Name of column containing the observation time.

value_name

Name of the column containing the measurement.

Value

An object of class AURMC containing arm-specific estimates and difference and ratio contrasts. Ratio inference is returned as NA when either arm-specific area is non-positive.

Examples

example_data <- data.frame(
  idx = rep(1:4, each = 2),
  arm = rep(c(0, 0, 1, 1), each = 2),
  time = rep(c(0, 1), 4),
  status = rep(c(1, 0), 4),
  value = rep(c(1, 1, 2, 2), each = 2)
)
CompareAURMCs(example_data, tau = 1)
example_data <- data.frame(
  idx = rep(1:4, each = 2),
  arm = rep(c(0, 0, 1, 1), each = 2),
  time = rep(c(0, 1), 4),
  status = rep(c(1, 0), 4),
  value = rep(c(1, 1, 2, 2), each = 2)
)
CompareAURMCs(example_data, tau = 1)

Estimate Curve

Description

Estimate Curve

Usage

Curve(
  data,
  censor_after_last = TRUE,
  idx_name = "idx",
  status_name = "status",
  time_name = "time",
  value_name = "value"
)
Curve(
  data,
  censor_after_last = TRUE,
  idx_name = "idx",
  status_name = "status",
  time_name = "time",
  value_name = "value"
)

Arguments

data

Data.frame.

censor_after_last

Introduce censoring after the last event if no observation-terminating event is present.

idx_name

Name of column containing a unique subject index.

status_name

Name of column containing the status. Must be coded as 0 for censoring, 1 for a measurement, 2 for death. Each subject should have an observation-terminating event, either censoring or death.

time_name

Name of column containing the observation time.

value_name

Name of the column containing the measurement.

Value

Function.

Draw Bootstrap R

Description

Draw Bootstrap R

Usage

DrawBootstrapR(idx, status, time, value)
DrawBootstrapR(idx, status, time, value)

Arguments

idx

Unique subject index.

status

Status, coded as 0 for censoring, 1 for a measurement, 2 for a terminal event.

time

Observation time.

value

Observation value.

Value

Numeric matrix.

Tabulate Estimator R

Description

Tabulate Estimator R

Usage

EstimatorR(
  idx,
  status,
  time,
  value,
  eval_times = NULL,
  int_method = "trapezoid",
  replace_na = FALSE,
  return_auc = FALSE,
  trunc_time = NULL
)
EstimatorR(
  idx,
  status,
  time,
  value,
  eval_times = NULL,
  int_method = "trapezoid",
  replace_na = FALSE,
  return_auc = FALSE,
  trunc_time = NULL
)

Arguments

idx

Unique subject index.

status

Status, coded as 0 for censoring, 1 for a measurement, 2 for a terminal event.

time

Observation time.

value

Observation value.

eval_times

Evaluation times. If omitted, defaults to the unique values of time.

int_method

Integration method, selected from "left", "right", "trapezoid".

replace_na

Replace NaN with zero? Default: FALSE.

return_auc

Return the AUC? Default: FALSE.

trunc_time

Truncation time? Optional. If omitted, defaults to the maximum evaluation time.

Value

Data.frame.

Simulate Repeated Measures Data

Description

Simulates repeated measures data at regular time points subject to exponential censoring and death.

Usage

GenData(
  censoring_rate,
  death_rate,
  n,
  tau,
  last_missing = FALSE,
  value_mean = 0,
  value_sd = 1
)
GenData(
  censoring_rate,
  death_rate,
  n,
  tau,
  last_missing = FALSE,
  value_mean = 0,
  value_sd = 1
)

Arguments

censoring_rate

Rate for the time to censoring.

death_rate

Rate for the time to death.

n

Number of subjects.

tau

Truncation time.

last_missing

Should the last value be missing? Default: FALSE.

value_mean

Mean of measurement.

value_sd

Standard deviation of measurement.

Value

A data.frame with subject index, observation time, status, and repeated measurement value.

Examples

set.seed(1)
GenData(censoring_rate = 0.5, death_rate = 0.25, n = 5, tau = 2)
set.seed(1)
GenData(censoring_rate = 0.5, death_rate = 0.25, n = 5, tau = 2)

Influence Function R

Description

Influence function contributions for the AUC. Includes the three component integrals (i1, i2, i3) and the overall influence psi.

Usage

InfluenceR(idx, status, time, trunc_time, value, int_method = "trapezoid")
InfluenceR(idx, status, time, trunc_time, value, int_method = "trapezoid")

Arguments

idx

Unique subject index.

status

Status, coded as 0 for censoring, 1 for a measurement, 2 for a terminal event.

time

Observation time.

trunc_time

Truncation time? Optional. If omitted, defaults to the maximum evaluation time.

value

Observation value.

int_method

Integration method, selected from "left", "right", "trapezoid".

Value

Data.frame.

Interpolate

Description

Linearly interpolates between each subject's measurements. The input data should contain no missing values.

Usage

Interpolate(
  data,
  grid,
  idx_name = "idx",
  status_name = "status",
  rm_na = TRUE,
  time_name = "time",
  value_name = "value"
)
Interpolate(
  data,
  grid,
  idx_name = "idx",
  status_name = "status",
  rm_na = TRUE,
  time_name = "time",
  value_name = "value"
)

Arguments

data

Data.frame.

grid

Grid of unique points at which to interpolate.

idx_name

Name of column containing a unique subject index.

status_name

Name of column containing the status. Must be coded as 0 for censoring, 1 for a measurement, 2 for death. Each subject should have an observation-terminating event, either censoring or death.

rm_na

Remove records interpolated to NA?

time_name

Name of column containing the observation time.

value_name

Name of the column containing the measurement.

Value

A data.frame containing subject index, status, time, and the interpolated value.

Notes

The grid of points will be augmented to include the time of each subjects observation terminating event.

Examples

example_data <- data.frame(
  idx = c(1, 1, 2, 2),
  status = c(1, 0, 1, 2),
  time = c(0, 1, 0, 1),
  value = c(0, 1, 0, -1)
)
Interpolate(example_data, grid = c(0, 0.5, 1))
example_data <- data.frame(
  idx = c(1, 1, 2, 2),
  status = c(1, 0, 1, 2),
  time = c(0, 1, 0, 1),
  value = c(0, 1, 0, -1)
)
Interpolate(example_data, grid = c(0, 0.5, 1))

Interpolation R Linearly interpolates between each subject's measurements. The input data should contain no missing values.

Description

Interpolation R

Linearly interpolates between each subject's measurements. The input data should contain no missing values.

Usage

InterpolateR(grid, idx, status, time, value)
InterpolateR(grid, idx, status, time, value)

Arguments

grid

Grid of unique points at which to interpolate.

idx

Unique subject index.

status

Status, coded as 0 for censoring, 1 for a measurement, 2 for a terminal event.

time

Observation time.

value

Observation value.

Value

Data.frame.

Tabulate Kaplan Meier R

Description

Constructs a matrix with evaluation times as rows, and 4 columns:

time Evaluation times.
nar Number at risk.
surv Left-limit survival probability, $\hat S(t-)$ .
haz Hazard.

Usage

KaplanMeierR(eval_times, idx, status, time)
KaplanMeierR(eval_times, idx, status, time)

Arguments

eval_times

Evaluation times.

idx

Unique subject index.

status

Status, coded as 0 for censoring, 1 for a measurement, 2 for a terminal event.

time

Observation time.

Value

Data.frame.

Perturbation R Generates realizations of $\frac{1}{n}\sum_{i=1}^{n}\psi_{i}w_{i}$ , where $\psi_{i}$ is the influence function for the ith subject and the $w_{i}$ are IID random weights.

Description

Perturbation R

Generates realizations of $\frac{1}{n}\sum_{i=1}^{n}\psi_{i}w_{i}$ , where $\psi_{i}$ is the influence function for the ith subject and the $w_{i}$ are IID random weights.

Usage

PerturbationR(
  idx,
  perturbations,
  status,
  time,
  trunc_time,
  value,
  int_method = "trapezoid"
)
PerturbationR(
  idx,
  perturbations,
  status,
  time,
  trunc_time,
  value,
  int_method = "trapezoid"
)

Arguments

idx

Unique subject index.

perturbations

Number of perturbations

status

Status, coded as 0 for censoring, 1 for a measurement, 2 for a terminal event.

time

Observation time.

trunc_time

Truncation time? Optional. If omitted, defaults to the maximum evaluation time.

value

Observation value.

int_method

Integration method, selected from "left", "right", "trapezoid".

Value

Numeric vector.

Notes

The random seed should be set in R prior to calling this function.

Plot Two Sample

Description

Plot Two Sample

Usage

PlotTwoSample(
  data,
  arm_name = "arm",
  censor_after_last = TRUE,
  color_labs = c("Ctrl", "Trt"),
  colors = c("#EFC000FF", "#6385B8"),
  eval_pts = 200,
  idx_name = "idx",
  show_auc = FALSE,
  show_nar = TRUE,
  status_name = "status",
  tau = NULL,
  time_name = "time",
  title = NULL,
  value_name = "value",
  x_breaks = NULL,
  x_labs = NULL,
  x_name = "Time",
  x_max = NULL,
  y_name = "Expected Value",
  y_lim = NULL
)
PlotTwoSample(
  data,
  arm_name = "arm",
  censor_after_last = TRUE,
  color_labs = c("Ctrl", "Trt"),
  colors = c("#EFC000FF", "#6385B8"),
  eval_pts = 200,
  idx_name = "idx",
  show_auc = FALSE,
  show_nar = TRUE,
  status_name = "status",
  tau = NULL,
  time_name = "time",
  title = NULL,
  value_name = "value",
  x_breaks = NULL,
  x_labs = NULL,
  x_name = "Time",
  x_max = NULL,
  y_name = "Expected Value",
  y_lim = NULL
)

Arguments

data

Data.frame.

arm_name

Name of the column containing treatment arm. Coded as 0 for reference, 1 for treatment.

censor_after_last

Introduce censoring after the last event if no observation-terminating event is present.

color_labs

Color labels.

colors

Colors for control and treatment respectively.

eval_pts

Evaluation points between 0 and tau.

idx_name

Name of column containing a unique subject index.

show_auc

Show area under the curve?

show_nar

Show number at risk?

status_name

Name of column containing the status. Must be coded as 0 for censoring, 1 for a measurement, 2 for death. Each subject should have an observation-terminating event, either censoring or death.

tau

Truncation time.

time_name

Name of column containing the observation time.

title

Plot title.

value_name

Name of the column containing the measurement.

x_breaks

X-axis breaks.

x_labs

X-axis labels.

x_name

X-axis name.

x_max

X-axis upper limit.

y_name

Y-axis name.

y_lim

Y-axis limits.

Value

ggplot

Print Method for AURMC Object

Description

Print method for objects of class AURMC.

Usage

## S3 method for class 'AURMC'
print(x, ...)
## S3 method for class 'AURMC'
print(x, ...)

Arguments

x

An object of class AURMC.

...

Unused.

Value

Invisibly returns NULL. This method is called for its side effect of displaying the reference-arm, treatment-arm, and contrast tables stored in x, with noninteger numeric values rounded to three significant digits.

Show Method for AURMC Object

Description

Show Method for AURMC Object

Usage

## S4 method for signature 'AURMC'
show(object)
## S4 method for signature 'AURMC'
show(object)

Arguments

object

An object of class AURMC.

Tabulate the Repeated Measures Curve

Description

Tabulate the Repeated Measures Curve

Usage

TabRMC(
  data,
  censor_after_last = TRUE,
  idx_name = "idx",
  status_name = "status",
  tau = NULL,
  time_name = "time",
  value_name = "value"
)
TabRMC(
  data,
  censor_after_last = TRUE,
  idx_name = "idx",
  status_name = "status",
  tau = NULL,
  time_name = "time",
  value_name = "value"
)

Arguments

data

Data.frame.

censor_after_last

Introduce censoring after the last event if no observation-terminating event is present.

idx_name

Name of column containing a unique subject index.

status_name

Name of column containing the status. Must be coded as 0 for censoring, 1 for a measurement, 2 for death. Each subject should have an observation-terminating event, either censoring or death.

tau

Truncation time.

time_name

Name of column containing the observation time.

value_name

Name of the column containing the measurement.

Value

A data.frame tabulating time, number and proportion at risk, terminal-event hazard, left-limit survival $\hat S(t-)$ , observed-value mean, and the estimated repeated measures curve.

Tabulate Value Matrix R

Description

Tabulate $D_{i}(t)$ with subjects as rows and evaluation times as columns.

Usage

ValueMatrixR(eval_times, idx, time, value)
ValueMatrixR(eval_times, idx, time, value)

Arguments

eval_times

Evaluation times.

idx

Unique subject index.

time

Observation time.

value

Observation value.

Value

Numeric matrix.

Package 'AURMC'

Help Index

Tabulate At-Risk Matrix R

Description

Usage

Arguments

Value

Area Under the Repeated Measures Curve

Description

Usage

Arguments

Value

Examples

AURMC Object

Description

Slots

Bootstrap Samples R

Description

Usage

Arguments

Value

Calculate Martingale

Description

Usage

Arguments

Value

Calculate Mu R

Description

Usage

Arguments

Value

Censor After Last

Description

Usage

Arguments

Value

Compare Areas Under Repeated Measures Curves

Description

Usage

Arguments

Value

Examples

Estimate Curve

Description

Usage

Arguments

Value

Draw Bootstrap R

Description

Usage

Arguments

Value

Tabulate Estimator R

Description

Usage

Arguments

Value

Simulate Repeated Measures Data

Description

Usage

Arguments

Value

Examples

Influence Function R

Description

Usage

Arguments

Value

Interpolate

Description

Usage

Arguments

Value

Notes

Examples

Interpolation R Linearly interpolates between each subject's measurements. The input data should contain no missing values.

Description

Usage

Arguments

Value

Perturbation R Generates realizations of $\frac{1}{n}\sum_{i=1}^{n}\psi_{i}w_{i}$ , where $\psi_{i}$ is the influence function for the ith subject and the $w_{i}$ are IID random weights.