Tau U effect size

Tau U effect size and variance computation.

Usage

tau_u_computation(
  data,
  studyID,
  subjectID,
  outcome_name,
  phase_name,
  phase_order = NULL,
  version = c("revised", "original"),
  baseline_trend_adjust = TRUE,
  variance_correction = c("none", "small_sample", "autocorrelation", "both"),
  na_option = "listwise"
)

Arguments

data

Raw data to compute the effect sizes and variances from

studyID

A character string representing the studyID

subjectID

A character string representing the subjectID

outcome_name

A character string representing the outcome name

phase_name

A character string representing the phase name

phase_order

Optional character vector of length 2 giving the baseline phase first and the comparison phase second. If NULL, factor levels are used when phase_name is a factor; otherwise the two unique phase labels are sorted alphabetically.

version

Character string selecting the baseline-trend-corrected Tau-U denominator. "revised" uses m * n; "original" uses m * n + m * (m - 1) / 2. When baseline_trend_adjust = FALSE, the unadjusted A-vs-B Tau always uses m * n.

baseline_trend_adjust

Logical. If TRUE, subtracts the baseline trend component from the phase contrast. If FALSE, returns the unadjusted A-vs-B nonoverlap Tau.

variance_correction

Character string selecting an optional multiplicative correction for the three variance approximations. "none" leaves v1, v2, and v3 unchanged. "small_sample" applies a finite-sample multiplier, "autocorrelation" applies an AR(1)-style lag-1 autocorrelation multiplier, and "both" applies both corrections.

na_option

Currently only listwise is supported

Value

Returns a data frame that contains the studyID, subjectID, and the Tau-U effect size and 3 different variance approximations: v1 is an empirical variance approximation based on the observed pairwise comparisons, v2 is a Mann-Whitney-style theoretical variance approximation that ignores baseline trend variability, and v3 is a phase-contrast variance approximation that adds a baseline-trend component when requested. The output also includes the lag-1 autocorrelation estimate used by the optional autocorrelation correction, the selected correction label, and the final variance multiplier applied to v1, v2, and v3.

Details

Tau-U is computed by contrasting the first phase in phase_order with the second. Supplying phase_order is recommended whenever the intended baseline and intervention labels are known. Each study-subject combination must contain observations from both phases. baseline_trend_adjust = TRUE computes the baseline-trend-corrected Tau-U; baseline_trend_adjust = FALSE computes the unadjusted A-vs-B nonoverlap Tau. For baseline-trend-corrected Tau-U, the revised denominator uses m * n, while the original denominator adds the baseline trend term m * (m - 1) / 2.

Let m be the number of baseline observations, n the number of comparison observations, Q_P the vector of pairwise phase-contrast signs comparing comparison observations to baseline observations, and Q_A the strictly upper-triangular baseline self-comparison signs used for the baseline trend adjustment. The Tau-U numerator is $$ N_U = \sum Q_P - I_{\mathrm{trend}} \sum Q_A, $$ where I_trend = 1 when baseline_trend_adjust = TRUE and 0 otherwise. The reported Tau-U is $$ \tau_U = N_U / d, $$ where d = m n for the revised version and for all unadjusted A-vs-B Tau values. The original baseline-trend-corrected version instead uses d = m n + m (m - 1) / 2. The revised denominator keeps Tau-U on the A-vs-B nonoverlap scale after removing baseline trend; the original denominator normalizes by all pairwise comparisons entering the adjusted numerator.

The three variance columns are intended to support different levels of approximation. Use v1 when the observed sign-comparison dispersion is preferred and the baseline phase is long enough to estimate it. Use v2 for the simpler Mann-Whitney approximation to the A-vs-B contrast. Use v3 when baseline-trend adjustment is part of the estimand and the uncertainty from the baseline-trend component should be represented.

The empirical variance approximation v1 is $$ \widehat{\mathrm{Var}}(\tau_U) = \frac{\widehat{\mathrm{Var}}(Q_P) \, (m n) + \widehat{\mathrm{Var}}(Q_A) \, m (m - 1) / 2}{d^2}, $$ where d = m n for the revised version and d = m n + m (m - 1) / 2 for the original baseline-trend-corrected version. When baseline_trend_adjust = FALSE, the Q_A term is omitted and d = m n.

The Mann-Whitney-style theoretical variance approximation v2 is $$ \mathrm{Var}(\tau_U) = \frac{m n (m + n + 1) / 12}{d^2}, $$ using the same denominator d.

The phase-contrast variance approximation v3 adds the baseline-trend component when baseline_trend_adjust = TRUE: $$ \mathrm{Var}_{\mathrm{pc}}(\tau_U) = \frac{m n (m + n + 1) / 12 + m (m - 1) (2 m + 5) / 72}{d^2}, $$ again with d = m n for the revised version and d = m n + m (m - 1) / 2 for the original baseline-trend-corrected version. When baseline_trend_adjust = FALSE, the baseline-trend component is omitted, so v2 and v3 are identical before optional corrections.

Two optional corrections can be applied to all three approximate variances. The small-sample correction multiplies the variances by (m + n) / (m + n - 1), reflecting that very short within-case series add extra uncertainty to approximate variance estimates. The autocorrelation correction estimates the lag-1 autocorrelation rho from the observed within-case outcome sequence, in the order rows appear in data, and applies the AR(1)-style design-effect multiplier $$ 1 + 2 \sum_{k = 1}^{m+n-1} (1 - k / (m+n)) \rho^k. $$ The package bounds this design-effect multiplier above zero before applying it. If autocorrelation cannot be estimated, the autocorrelation multiplier is set to 1 and autocorrelation is returned as NA. With variance_correction = "both", the final multiplier is the product of the small-sample and autocorrelation multipliers: $$ \widehat{\mathrm{Var}}_{\mathrm{corrected}}(\tau_U) = c \widehat{\mathrm{Var}}(\tau_U). $$

Examples

scd <- data.frame(
  study = "S1",
  subject = "P1",
  phase = rep(c("A", "B"), each = 4),
  outcome = c(2, 3, 3, 4, 5, 6, 6, 7)
)
tau_u_computation(
  scd,
  studyID = "study",
  subjectID = "subject",
  outcome_name = "outcome",
  phase_name = "phase",
  phase_order = c("A", "B")
)
#>        study subject  Tau_U         v1       v2         v3 autocorrelation
#> S1||P1    S1      P1 0.6875 0.00390625 0.046875 0.05533854       0.9519231
#>        variance_correction variance_multiplier
#> S1||P1                none                   1