Package 'winr' reference manual

Title:	Randomization-Based Covariance Adjustment of Win Statistics
Description:	A multi-visit clinical trial may collect participant responses on an ordinal scale and may utilize a stratified design, such as randomization within centers, to assess treatment efficacy across multiple visits. Baseline characteristics may be strongly associated with the outcome, and adjustment for them can improve power. The win ratio (ignores ties) and the win odds (accounts for ties) can be useful when analyzing these types of data from randomized controlled trials. This package provides straightforward functions for adjustment of the win ratio and win odds for stratification and baseline covariates, facilitating the comparison of test and control treatments in multi-visit clinical trials. For additional information concerning the methodologies and applied examples within this package, please refer to the following publications: 1. Weideman, A.M.K., Kowalewski, E.K., & Koch, G.G. (2024). “Randomization-based covariance adjustment of win ratios and win odds for randomized multi-visit studies with ordinal outcomes.” Journal of Statistical Research, 58(1), 33–48. <doi:10.3329/jsr.v58i1.75411>. 2. Kowalewski, E.K., Weideman, A.M.K., & Koch, G.G. (2023). “SAS macro for randomization-based methods for covariance and stratified adjustment of win ratios and win odds for ordinal outcomes.” SESUG 2023 Proceedings, Paper 139-2023.
Authors:	Ann Marie K. Weideman [aut, cre], Elaine K. Kowalewski [aut], Gary G. Koch [aut]
Maintainer:	Ann Marie K. Weideman <[email protected]>
License:	MIT + file LICENSE
Version:	1.0.0
Built:	2024-11-17 05:56:12 UTC
Source:	https://github.com/cran/winr

Adjusted win odds

Description

Randomization-based adjustment of the win odds for baseline covariates and strata.

Usage

adj_winodds(
  data,
  pid,
  baseline = NULL,
  outcome,
  covars = NULL,
  strata = NULL,
  arm,
  method = "small",
  sig.level = 0.05
)
adj_winodds(
  data,
  pid,
  baseline = NULL,
  outcome,
  covars = NULL,
  strata = NULL,
  arm,
  method = "small",
  sig.level = 0.05
)

Arguments

`data`	a dataframe or matrix containing the analysis data. Must be in wide format such that a participant's repeated responses are in a single row, and each response is in a separate column.
`pid`	a string indicating the name of the variable corresponding to participant ID.
`baseline`	a string indicating the name of the outcome measured at baseline. If not specified, defaults to NULL, and no baseline adjustment is employed.
`outcome`	a vector of strings indicating the names of the outcomes measured at each visit. Baseline, if specified, will be concatenated to this vector within the code. The outcomes must have at least an ordinal measurement scale with larger values being better than smaller values. Thus, the outcome can be ordered categories or continuous measurements.
`covars`	a vector of strings indicating the names of the covariates (measured at baseline) used for adjustment. These covariates must be numeric and can be measured on a binary, categorical, ordered categorical, or continuous scale. If not specified, defaults to NULL and no covariate adjustment is employed.
`strata`	a string indicating the name of the variable used for stratification. If not specified, defaults to NULL and no stratification adjustment is utilized.
`arm`	a string indicating the name of the variable for treatment arm. Treatment arm must be a positive integer such that the test treatment arm is ALWAYS higher in value than the control arm.
`method`	a string "small" or "large" used to denote the sample size method employed. The small sample size method is recommended unless within-stratum sample size is reasonably large (e.g., >= 50), number of visits is small (e.g., <=6), and number of covariates is small (e.g., <=4). Defaults to "small."
`sig.level`	significance level (Type I error probability). Defaults to 0.05.

Value

A dataframe containing:

`logWR`	natural log-transformed win ratio
`SE_logWR`	standard error of log-transformed win ratio
`Var_logWR`	sample variance of log-transformed win ratio
`Chi_Square`	Pearson's Chi-squared test statistic corresponding to logWR
`p_value`	p-value corresponding to the Pearson's Chi-squared test
`WR`	win ratio
`LCL_WR`	lower bound of $(1-\alpha/2)\times 100\%$ CI for WR
`UCL_WR`	upper bound of $(1-\alpha/2)\times 100\%$ CI for WR

Examples


#--------------------------
# Respiratory example
#--------------------------

# Since IDs repeat at centers 1 and 2, create a new, unique ID
resp$UniqID<-resp$Center*100+resp$ID

# Convert treatment arm to binary
resp$Trt<-1*(resp$Treatment=="T")

# Indicator for male
resp$SexNum<-1*(resp$Sex=="M")

adj_winodds(data=resp,
            pid="UniqID",
            baseline="Baseline",
            outcome=c("Visit1","Visit2","Visit3","Visit4"),
            covars= c("SexNum","Age"),
            strata="Center",
            arm="Trt",
            method="small",
            sig.level=0.05)

#----------------------
# Dermatology example
#----------------------

#Generate indicators for stage 4 and 5
skin$Stage4 = (skin$STAGE == 4)*1
skin$Stage5 = (skin$STAGE == 5)*1

# Generate treatment center
skin$center<-ifelse(skin$INV==5,1,
  ifelse(skin$INV==6,2,
    ifelse(skin$INV==8,3,
      ifelse(skin$INV==9,4,
        ifelse(skin$INV==10,5,6)))))

# Generate treatment center that pools centers 3 and 4 due to small sample size
skin$center2 = skin$center
skin$center2<-ifelse(skin$center == 4, 3, skin$center)

# Generate participant IDs
skin$ID<-1:nrow(skin)

adj_winodds(data=skin,
            pid="ID",
            baseline=NULL,
            outcome=c("R1","R2","R3"),
            covars= c("Stage4","Stage5"),
            strata="center2",
            arm="TRT",
            method="small",
            sig.level=0.05)

#--------------------------
# Respiratory example
#--------------------------

# Since IDs repeat at centers 1 and 2, create a new, unique ID
resp$UniqID<-resp$Center*100+resp$ID

# Convert treatment arm to binary
resp$Trt<-1*(resp$Treatment=="T")

# Indicator for male
resp$SexNum<-1*(resp$Sex=="M")

adj_winodds(data=resp,
            pid="UniqID",
            baseline="Baseline",
            outcome=c("Visit1","Visit2","Visit3","Visit4"),
            covars= c("SexNum","Age"),
            strata="Center",
            arm="Trt",
            method="small",
            sig.level=0.05)

#----------------------
# Dermatology example
#----------------------

#Generate indicators for stage 4 and 5
skin$Stage4 = (skin$STAGE == 4)*1
skin$Stage5 = (skin$STAGE == 5)*1

# Generate treatment center
skin$center<-ifelse(skin$INV==5,1,
  ifelse(skin$INV==6,2,
    ifelse(skin$INV==8,3,
      ifelse(skin$INV==9,4,
        ifelse(skin$INV==10,5,6)))))

# Generate treatment center that pools centers 3 and 4 due to small sample size
skin$center2 = skin$center
skin$center2<-ifelse(skin$center == 4, 3, skin$center)

# Generate participant IDs
skin$ID<-1:nrow(skin)

adj_winodds(data=skin,
            pid="ID",
            baseline=NULL,
            outcome=c("R1","R2","R3"),
            covars= c("Stage4","Stage5"),
            strata="center2",
            arm="TRT",
            method="small",
            sig.level=0.05)

Adjusted win ratio

Description

Randomization-based adjustment of the win ratio for baseline covariates and strata.

Usage

adj_winratio(
  data,
  pid,
  baseline = NULL,
  outcome,
  covars = NULL,
  strata = NULL,
  arm,
  method = "small",
  sig.level = 0.05
)
adj_winratio(
  data,
  pid,
  baseline = NULL,
  outcome,
  covars = NULL,
  strata = NULL,
  arm,
  method = "small",
  sig.level = 0.05
)

Arguments

`data`	a dataframe or matrix containing the analysis data. Must be in wide format such that a participant's repeated responses are in a single row, and each response is in a separate column.
`pid`	a string indicating the name of the variable corresponding to participant ID.
`baseline`	a string indicating the name of the outcome measured at baseline. If not specified, defaults to NULL, and no baseline adjustment is employed.
`outcome`	a vector of strings indicating the names of the outcomes measured at each visit. Baseline, if specified, will be concatenated to this vector within the code. The outcomes must have at least an ordinal measurement scale with larger values being better than smaller values. Thus, the outcome can be ordered categories or continuous measurements.
`covars`	a vector of strings indicating the names of the covariates (measured at baseline) used for adjustment. These covariates must be numeric and can be measured on a binary, categorical, ordered categorical, or continuous scale. If not specified, defaults to NULL and no covariate adjustment is employed.
`strata`	a string indicating the name of the variable used for stratification. If not specified, defaults to NULL and no stratification adjustment is utilized.
`arm`	a string indicating the name of the variable for treatment arm. Treatment arm must be a positive integer such that the test treatment arm is ALWAYS higher in value than the control arm.
`method`	a string "small" or "large" used to denote the sample size method employed. The small sample size method is recommended unless within-stratum sample size is reasonably large (e.g., >= 50), number of visits is small (e.g., <=6), and number of covariates is small (e.g., <=4). Defaults to "small."
`sig.level`	significance level (Type I error probability). Defaults to 0.05.

Value

A dataframe containing:

`logWR`	natural log-transformed win ratio
`SE_logWR`	standard error of log-transformed win ratio
`Var_logWR`	sample variance of log-transformed win ratio
`Chi_Square`	Pearson's Chi-squared test statistic corresponding to logWR
`p_value`	p-value corresponding to the Pearson's Chi-squared test
`WR`	win ratio
`LCL_WR`	lower bound of $(1-\alpha/2)\times 100\%$ CI for WR
`UCL_WR`	upper bound of $(1-\alpha/2)\times 100\%$ CI for WR

Examples


#--------------------------
# Respiratory example
#--------------------------

# Since IDs repeat at centers 1 and 2, create a new, unique ID
resp$UniqID<-resp$Center*100+resp$ID

# Convert treatment arm to binary
resp$Trt<-1*(resp$Treatment=="T")

# Indicator for male
resp$SexNum<-1*(resp$Sex=="M")

adj_winratio(data=resp,
            pid="UniqID",
            baseline="Baseline",
            outcome=c("Visit1","Visit2","Visit3","Visit4"),
            covars= c("SexNum","Age"),
            strata="Center",
            arm="Trt",
            method="small",
            sig.level=0.05)

#----------------------
# Dermatology example
#----------------------

#Generate indicators for stage 4 and 5
skin$Stage4 = (skin$STAGE == 4)*1
skin$Stage5 = (skin$STAGE == 5)*1

# Generate treatment center
skin$center<-ifelse(skin$INV==5,1,
  ifelse(skin$INV==6,2,
    ifelse(skin$INV==8,3,
      ifelse(skin$INV==9,4,
        ifelse(skin$INV==10,5,6)))))

# Generate treatment center that pools centers 3 and 4 due to small sample size
skin$center2 = skin$center
skin$center2<-ifelse(skin$center == 4, 3, skin$center)

# Generate participant IDs
skin$ID<-1:nrow(skin)

adj_winratio(data=skin,
            pid="ID",
            baseline=NULL,
            outcome=c("R1","R2","R3"),
            covars= c("Stage4","Stage5"),
            strata="center2",
            arm="TRT",
            method="small",
            sig.level=0.05)

#--------------------------
# Respiratory example
#--------------------------

# Since IDs repeat at centers 1 and 2, create a new, unique ID
resp$UniqID<-resp$Center*100+resp$ID

# Convert treatment arm to binary
resp$Trt<-1*(resp$Treatment=="T")

# Indicator for male
resp$SexNum<-1*(resp$Sex=="M")

adj_winratio(data=resp,
            pid="UniqID",
            baseline="Baseline",
            outcome=c("Visit1","Visit2","Visit3","Visit4"),
            covars= c("SexNum","Age"),
            strata="Center",
            arm="Trt",
            method="small",
            sig.level=0.05)

#----------------------
# Dermatology example
#----------------------

#Generate indicators for stage 4 and 5
skin$Stage4 = (skin$STAGE == 4)*1
skin$Stage5 = (skin$STAGE == 5)*1

# Generate treatment center
skin$center<-ifelse(skin$INV==5,1,
  ifelse(skin$INV==6,2,
    ifelse(skin$INV==8,3,
      ifelse(skin$INV==9,4,
        ifelse(skin$INV==10,5,6)))))

# Generate treatment center that pools centers 3 and 4 due to small sample size
skin$center2 = skin$center
skin$center2<-ifelse(skin$center == 4, 3, skin$center)

# Generate participant IDs
skin$ID<-1:nrow(skin)

adj_winratio(data=skin,
            pid="ID",
            baseline=NULL,
            outcome=c("R1","R2","R3"),
            covars= c("Stage4","Stage5"),
            strata="center2",
            arm="TRT",
            method="small",
            sig.level=0.05)

The respiratory dataset originates from a randomized clinical trial that evaluated a test treatment against a control in managing a chronic respiratory condition (Koch et al. 1989; Stokes et al. 2012). The study involved 111 patients—54 receiving the active treatment and 57 on a placebo—distributed across two centers. Assessments were conducted at baseline and during four subsequent follow-up visits. At each visit, patients' respiratory status was evaluated using an ordinal scale where 0 signifies ‘terrible’, 1 is ‘poor’, 2 stands for ‘fair’, 3 represents ‘good’, and 4 denotes ‘excellent’. The participating centers serve as stratification factors, and the baseline variables include age, sex, and initial respiratory status.

Usage

resp
resp

Format

A data frame with 10 variables.

ID: Participant ID

Center: Treatment center

Sex: Participant sex at birth

Age: Participant age at baseline

Treatment: T=treatment arm, C=control arm

Baseline: Ordinal global rating at Baseline: 0 for terrible, 1 for poor, 2 for fair, 3 for good, and 4 for excellent

Visit1: Ordinal global rating at Visit 1: 0 for terrible, 1 for poor, 2 for fair, 3 for good, and 4 for excellent

Visit2: Ordinal global rating at Visit 2: 0 for terrible, 1 for poor, 2 for fair, 3 for good, and 4 for excellent

Visit3: Ordinal global rating at Visit 3: 0 for terrible, 1 for poor, 2 for fair, 3 for good, and 4 for excellent

Visit4: Ordinal global rating at Visit 4: 0 for terrible, 1 for poor, 2 for fair, 3 for good, and 4 for excellent

References

Koch GG, Carr GJ, Amara IA, Stokes ME, Uryniak TJ (1989). “Categorical Data Analysis.” In Berry DA (ed.), Statistical Methodology in the Pharmaceutical Sciences, 389-473. CRC Press.

Stokes ME, Davis CS, Koch GG (2012). Categorical data analysis using SAS, third edition. SAS Institute.

Dermatology dataset

Description

The dermatology dataset is derived from a randomized clinical trial that compared a test treatment with a control for managing skin conditions (Stanish et al. 1978). This trial enrolled 172 patients—88 in the test group and 84 in the placebo group—across six clinics. These patients were assessed at three follow-up visits, where the degree of improvement in their skin condition was measured on a five-point scale: 1 for rapidly improving, 2 for slowly improving, 3 for stable, 4 for slowly worsening, and 5 for rapidly worsening. Due to Clinic 9 enrolling only four patients, data from Clinics 8 and 9 were combined, a decision supported by these clinics having the smallest sample sizes in their strata. The primary baseline variable recorded was the stage of disease at the start of the study, categorized as 3 for fair, 4 for poor, and 5 for exacerbation. This dataset also features missing data at follow-up visits, progressively increasing from 2% (3 missing observations) at the first visit to 9% (16 missing) at the second, and 17% (30 missing) at the third visit.

Usage

skin
skin

Format

A data frame with 11 variables.

INV: Investigator identification number (5,6,8,9,10,11)

ID: Participant ID

center: Treatment center

center2: Treatment center that pools centers 3 and 4 due to small sample size

TRT: 1 = Test drug, 2 = Placebo

STAGE: Initial stage of disease (3 = Fair, 4 = Poor, 5 = Exacerbation)

R1: Response at Time 1; NA if missing

R2: Response at Time 2; NA if missing

R3: Response at Time 3; NA if missing

Stage4: 1 if Stage 4, 0 otherwise

Stage5: 1 if Stage 5, 0 otherwise

References

Stanish WM, Gillings DB, Koch GG (1978). “An Application of Multivariate Ratio Methods for the Analysis of a Longitudinal Clinical Trial with Missing Data.” Biometrics, 34(2), 305–317. ISSN 0006341X, 15410420, http://www.jstor.org/stable/2530021.

Package 'winr'

Help Index

Adjusted win odds

Description

Usage

Arguments

Value

Examples

Adjusted win ratio

Description

Usage

Arguments

Value

Examples

Respiratory dataset

Description

Usage

Format

References

Dermatology dataset

Description

Usage

Format

References