Package 'CompAREdesign'

ARE method for composite binary endpoints

Description

The composite endpoint is assumed to be a binary endpoint formed by a combination of two events (E1 and E2). We assume that the endpoint 1 is more relevant for the clinical question than endpoint 2. This function calculates the ARE method for binary endpoints. The method quantifies the differences in efficiency of using the composite or the relevant as primary endpoint to lead the trial and, moreover, provides a decision rule to choose the primary endpoint. If the ARE is larger than 1, the composite endpoint may be considered the best option as primary endpoint. Otherwise, the relevant endpoint is preferred.

Usage

ARE_cbe(
  p0_e1,
  p0_e2,
  eff_e1,
  effm_e1 = "or",
  eff_e2,
  effm_e2 = "or",
  effm_ce = "or",
  rho
)

Arguments

p0_e1	numeric parameter, probability of occurrence E1 in the control group
p0_e2	numeric parameter, probability of occurrence E2 in the control group
eff_e1	numeric parameter, anticipated effect for the composite component E1
effm_e1	Effect measure used for the event E1 (effm_e1 = "diff" for difference of proportions, effm_e1 = "rr" for risk ratio, effm_e1 = "or" for odds ratio)
eff_e2	numeric parameter, anticipated effect for the composite component E2
effm_e2	Effect measure used for the event E2 (effm_e2 = "diff" for difference of proportions, effm_e2 = "rr" for risk ratio, effm_e2 = "or" for odds ratio)
effm_ce	Effect measure used for the composite endpoint (effm_ce = "diff" for difference of proportions, effm_ce = "rr" for risk ratio, effm_ce = "or" for odds ratio)
rho	numeric parameter, Pearson's correlation between the two events E1 and E2

Details

The input parameters stand for the probability of the composite components and Pearson's correlation between the two components. Note that Pearson's correlation takes values between two bounds that depend on the probabilities p0_e1 and p0_e2. To calculate the correlation bounds you can use the R functions lower_corr and upper_corr, available in this package.

Value

Returns the ARE value. If the ARE value is larger than 1 then the composite endpoint is preferred over the relevant endpoint. Otherwise, the endpoint 1 is preferred as the primary endpoint of the study.

References

Bofill Roig, M., & Gomez Melis, G. (2018). Selection of composite binary endpoints in clinical trials. Biometrical Journal, 60(2), 246-261. https://doi.org/10.1002/bimj.201600229

---

ARE method for composite time to event endpoints

Description

The composite endpoint is assumed to be a time to event endpoint formed by a combination of two events (E1 and E2). We assume that the endpoint 1 is more relevant for the clinical question than endpoint 2. This function calculates the ARE (Asymptotic Relative Efficiency) method for time to event endpoints. The method quantifies the differences in efficiency of using the composite or the relevant as primary endpoint to lead the trial and, moreover, provides a decision rule to choose the primary endpoint. If the ARE is larger than 1, the composite endpoint may be considered the best option as primary endpoint. Otherwise, the relevant endpoint is preferred.

Usage

ARE_tte(
  p0_e1,
  p0_e2,
  HR_e1,
  HR_e2,
  beta_e1 = 1,
  beta_e2 = 1,
  case,
  copula = "Frank",
  rho = 0.3,
  rho_type = "Spearman",
  subdivisions = 50,
  plot_print = FALSE,
  plot_save = FALSE
)

Arguments

p0_e1	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E1
p0_e2	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E2
HR_e1	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E1
HR_e2	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E2
beta_e1	numeric positive parameter, shape parameter ($\beta_1$) for a Weibull distribution for the endpoint E1 in the control group. See details for more info.
beta_e2	numeric positive parameter, shape parameter ($\beta_2$) for a Weibull distribution for the endpoint E2 in the control group. See details for more info.
case	integer parameter in {1,2,3,4}: (1) none of the endpoints is death; (2) endpoint 2 is death; (3) endpoint 1 is death; (4) both endpoints are death by different causes.
copula	character indicating the copula to be used: "Frank" (default), "Gumbel" or "Clayton". See details for more info.
rho	numeric parameter between -1 and 1, Spearman's correlation coefficient o Kendall Tau between the marginal distribution of the times to the two events E1 and E2. See details for more info.
rho_type	character indicating the type of correlation to be used: "Spearman" (default) or "Kendall". See details for more info.
subdivisions	integer parameter greater than or equal to 10. Number of points used to plot the ARE according to correlation. The default is 50. Ignored if plot_print=FALSE and plot_save=FALSE.
plot_print	logical indicating if the ARE according to the correlation should be displayed. The default is FALSE
plot_save	logical indicating if the plot of ARE according to the correlation is stored for future customization. The default is FALSE

Details

Some parameters might be difficult to anticipate, especially the shape parameters of Weibull distributions and those referred to the relationship between the marginal distributions. For the shape parameters (beta_e1, beta_e2) of the Weibull distribution, we recommend to use $\beta_j=0.5$, $\beta_j=1$ or $\beta_j=2$ if a decreasing, constant or increasing rates over time are expected, respectively. For the correlation (rho) between both endpoints, generally a positive value is expected as it has no sense to design an study with two endpoints negatively correlated. We recommend to use $\rho=0.1$, $\rho=0.3$ or $\rho=0.5$ for weak, mild and moderate correlations, respectively. For the type of correlation (rho_type), although two different type of correlations are implemented, we recommend the use of the Spearman's correlation. In any case, if no information is available on these parameters, we recommend to use the default values provided by the function.

Value

Returns the ARE value along with the fixed correlation. If the ARE value is larger than 1 then the composite endpoint is preferred over the relevant endpoint. Otherwise, the endpoint 1 is preferred as the primary endpoint of the study. In addition, if plot_save=TRUE an object of class ggplot with the ARE according to the correlation is stored in the output.

References

Gomez Melis, G. and Lagakos, S.W. (2013). Statistical considerations when using a composite endpoint for comparing treatment groups. Statistics in Medicine. Vol 32(5), pp. 719-738. https://doi.org/10.1002/sim.5547

Examples

# ARE for a specific study where the composite endpoint is recommended
ARE_tte(p0_e1=0.1, p0_e2=0.1, HR_e1=0.9, HR_e2=0.8, beta_e1 = 1, beta_e2 = 1, 
case=1, copula = "Frank", rho = 0.3, rho_type = "Spearman")
# ARE for a specific study where the composite endpoint is not recommended
ARE_tte(p0_e1=0.1, p0_e2=0.05, HR_e1=0.6, HR_e2=0.8, beta_e1 = 1, beta_e2 = 1, 
case=1, copula = "Frank", rho = 0.3, rho_type = "Spearman")

---

Effect for composite binary endpoints

Description

This function calculates different effect measures for binary composite outcomes. The composite endpoint is assumed to be a binary endpoint formed by a combination of two events (E1 and E2). The effect size is calculated on the basis of anticipated information on the composite components and the correlation between them. The function allows to compute the effect size in terms of the risk difference, risk ratio and odds ratio.

Usage

effectsize_cbe(
  p0_e1,
  p0_e2,
  eff_e1,
  effm_e1,
  eff_e2,
  effm_e2,
  effm_ce = "diff",
  rho
)

Arguments

p0_e1	numeric parameter, probability of occurrence E1 in the control group
p0_e2	numeric parameter, probability of occurrence E2 in the control group
eff_e1	numeric parameter, anticipated effect for the composite component E1
effm_e1	Effect measure used for the event E1 (effm_e1 = "diff" for difference of proportions, effm_e1 = "rr" for risk ratio, effm_e1 = "or" for odds ratio)
eff_e2	numeric parameter, anticipated effect for the composite component E2
effm_e2	Effect measure used for the event E2 (effm_e2 = "diff" for difference of proportions, effm_e2 = "rr" for risk ratio, effm_e2 = "or" for odds ratio)
effm_ce	Effect measure used for the composite endpoint (effm_ce = "diff" for difference of proportions, effm_ce = "rr" for risk ratio, effm_ce = "or" for odds ratio)
rho	numeric parameter, Pearson's correlation between the two events E1 and E2

Details

The input parameters stand for the probability of the composite components and Pearson's correlation between the two components. Note that Pearson's correlation takes values between two bounds that depend on the probabilities p0_e1 and p0_e2. To calculate the correlation bounds you can use the R functions lower_corr and upper_corr, available in this package.

Value

Returns the effect for the composite binary endpoint and the effects for the composite components.

References

Bofill Roig, M., & Gómez Melis, G. (2019). A new approach for sizing trials with composite binary endpoints using anticipated marginal values and accounting for the correlation between components. Statistics in Medicine, 38(11), 1935-1956. https://doi.org/10.1002/sim.8092

---

Effect for composite time-to-event endpoints

Description

This function calculates different effect measures for time-to-event composite outcomes. The composite endpoint is assumed to be a time-to-event endpoint formed by a combination of two events (E1 and E2). The effect size is calculated on the basis of anticipated information on the composite components and the correlation between them. Marginal distributions are assumed weibull for both endpoints. The function allows to compute the effect size in terms of the geometric average hazard ratio, the average hazard ratio, the ratio of restricted mean survival times and the median survival time ratio.

Usage

effectsize_tte(
  p0_e1,
  p0_e2,
  HR_e1,
  HR_e2,
  beta_e1 = 1,
  beta_e2 = 1,
  case,
  copula = "Frank",
  rho = 0.3,
  rho_type = "Spearman",
  followup_time = 1,
  subdivisions = 1000,
  plot_print = FALSE,
  plot_save = FALSE
)

Arguments

p0_e1	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E1
p0_e2	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E2
HR_e1	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E1
HR_e2	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E2
beta_e1	numeric positive parameter, shape parameter ($\beta_1$) for a Weibull distribution for the endpoint E1 in the control group. See details for more info.
beta_e2	numeric positive parameter, shape parameter ($\beta_2$) for a Weibull distribution for the endpoint E2 in the control group. See details for more info.
case	integer parameter in {1,2,3,4}: (1) none of the endpoints is death; (2) endpoint 2 is death; (3) endpoint 1 is death; (4) both endpoints are death by different causes.
copula	character indicating the copula to be used: "Frank" (default), "Gumbel" or "Clayton". See details for more info.
rho	numeric parameter between -1 and 1, Spearman's correlation coefficient o Kendall Tau between the marginal distribution of the times to the two events E1 and E2. See details for more info.
rho_type	character indicating the type of correlation to be used: "Spearman" (default) or "Kendall". See details for more info.
followup_time	numeric parameter indicating the maximum follow up time (in any unit). Default is 1.
subdivisions	integer parameter greater than or equal to 10. Number of subintervals to estimate the effect size. The default is 1000.
plot_print	logical indicating if the HR over time should be displayed. The default is FALSE
plot_save	logical indicating if the plot of HR over time should is stored for future customization. The default is FALSE

Details

Some parameters might be difficult to anticipate, especially the shape parameters of Weibull distributions and those referred to the relationship between the marginal distributions. For the shape parameters (beta_e1, beta_e2) of the Weibull distribution, we recommend to use $\beta_j=0.5$, $\beta_j=1$ or $\beta_j=2$ if a decreasing, constant or increasing rates over time are expected, respectively. For the correlation (rho) between both endpoints, generally a positive value is expected as it has no sense to design an study with two endpoints negatively correlated. We recommend to use $\rho=0.1$, $\rho=0.3$ or $\rho=0.5$ for weak, mild and moderate correlations, respectively. For the type of correlation (rho_type), although two different type of correlations are implemented, we recommend the use of the Spearman's correlation. In any case, if no information is available on these parameters, we recommend to use the default values provided by the function.

All returned expected effect sizes for the composite endpoint should be interpreted in relative terms (treated to control). gAHR and AHR represent the risk reduction that will be achieved with the new therapy, while RMST_ratio and Median_ratio represent the gain in time gain terms until the event.

Value

A list formed by two lists: effect_size, which contains the expected treatment effect measures and measures_by_group, which contains some relevant measures for each group

effect_size list:

gAHR

geometric Average Hazard Ratio

AHR

Average Hazard Ratio

RMST_ratio

Restricted Mean Survival Time Ratio

Median_ratio

Median Survival Time Ratio

measures_by_group list:

pstar

array with the probability of observing the composite event for each group

p1

array with the probability of observing the first event for each group

p2

array with the probability of observing the second event for each group

RMST

array with the restricted mean survival time for each group

Median

array with the median surival time for each group

In addition, if plot_save=TRUE an object of class ggplot with the HR over time for composite endpoint is stored in the list.

References

Schemper, M., Wakounig, S., Heinze, G. (2009). The estimation of average hazard ratios by weighted Cox regression. Stat. in Med. 28(19): 2473–2489. doi:10.1002/sim.3623

Examples

effectsize_tte(p0_e1   = .59, p0_e2   = .74, 
               HR_e1   = .91, HR_e2   = .77, 
               beta_e1 = 1,   beta_e2 = 2, 
               case    = 3,   rho     = .5,
               copula  = 'Frank', rho_type   = 'Spearman',
               plot_print = TRUE, plot_save = FALSE)

---

Lower bound for Pearson's Correlation

Description

Pearson's correlation between two binary outcomes takes values between two bounds defined according to the probabilities of the binary outcomes. This function calculates the lower bound of the correlation based on the probabilities of two binary outcomes.

Usage

lower_corr(p_e1, p_e2)

Arguments

p_e1	numeric parameter, probability of the event E1
p_e2	numeric parameter, probability of the event E2

Details

lower_corr returns a numeric value between -1 and 0.

Value

Returns the minimum value that the correlation between the two outcomes can take.

Examples

CompAREdesign::lower_corr(p_e1=0.1, p_e2=0.6)

---

Plot graphics related to the composite endpoint.

Description

Plot the survival function and the HR for composite endpoint over time and the ARE (Assymptotic Relative Efficiency) and sample size size according to the correlation.The composite endpoint is assumed to be a time to event endpoint formed by a combination of two events (E1 and E2). We assume that the endpoint 1 is more relevant for the clinical question than endpoint 2. #'

Usage

plot_tte(
  p0_e1,
  p0_e2,
  HR_e1,
  HR_e2,
  beta_e1 = 1,
  beta_e2 = 1,
  case,
  copula = "Frank",
  rho = 0.3,
  rho_type = "Spearman",
  followup_time = 1,
  alpha = 0.05,
  power = 0.8,
  ss_formula = "schoenfeld",
  summary = FALSE,
  type = "survival"
)

Arguments

p0_e1	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E1
p0_e2	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E2
HR_e1	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E1
HR_e2	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E2
beta_e1	numeric positive parameter, shape parameter ($\beta_1$) for a Weibull distribution for the endpoint E1 in the control group. See details for more info.
beta_e2	numeric positive parameter, shape parameter ($\beta_2$) for a Weibull distribution for the endpoint E2 in the control group. See details for more info.
case	integer parameter in {1,2,3,4}: (1) none of the endpoints is death; (2) endpoint 2 is death; (3) endpoint 1 is death; (4) both endpoints are death by different causes.
copula	character indicating the copula to be used: "Frank" (default), "Gumbel" or "Clayton". See details for more info.
rho	numeric parameter between -1 and 1, Spearman's correlation coefficient o Kendall Tau between the marginal distribution of the times to the two events E1 and E2. See details for more info.
rho_type	character indicating the type of correlation to be used: "Spearman" (default) or "Kendall". See details for more info.
followup_time	numeric parameter indicating the maximum follow up time (in any unit). Default is 1.
alpha	numeric parameter. The probability of type I error. By default $\alpha=0.05$
power	numeric parameter. The power to detect the treatment effect. By default $1-\beta=0.80$
ss_formula	character indicating the formula to be used for the sample size calculation on the single components: 'schoenfeld' (default) or 'freedman'
summary	logical. TRUE if you want all the relevant plots for the trial design
type	character indicating the type of plot: 'survival', 'effect', 'ARE', 'samplesize'

Details

Some parameters might be difficult to anticipate, especially the shape parameters of Weibull distributions and those referred to the relationship between the marginal distributions. For the shape parameters (beta_e1, beta_e2) of the Weibull distribution, we recommend to use $\beta_j=0.5$, $\beta_j=1$ or $\beta_j=2$ if a decreasing, constant or increasing rates over time are expected, respectively. For the correlation (rho) between both endpoints, generally a positive value is expected as it has no sense to design an study with two endpoints negatively correlated. We recommend to use $\rho=0.1$, $\rho=0.3$ or $\rho=0.5$ for weak, mild and moderate correlations, respectively. For the type of correlation (rho_type), although two different type of correlations are implemented, we recommend the use of the Spearman's correlation. In any case, if no information is available on these parameters, we recommend to use the default values provided by the function.

Value

Four plots related to composite endpoint are returned:

S

Survival curve for the composite endpoint over time

HR

Hazard Ratio for the composite endpoint over time

ARE

ARE according to correlation ($\rho$)

SS

Sample size for the composite endpoint according to correlation ($\rho$)

Examples

library(ggplot2)
plot_tte(p0_e1   = .59, p0_e2   = .74, 
         HR_e1   = .91, HR_e2   = .77, 
         beta_e1 = 1,   beta_e2 = 2, 
         case    = 3,   rho     = .5,
         copula  = 'Frank', rho_type = 'Spearman',
         summary = FALSE,   type = 'effect', 
         followup_time=1) + theme_bw()

---

Probability of composite binary endpoints

Description

This function calculates the probability of the composite binary endpoint formed by a combination of two events (E1 and E2). This probability is calculated by means of the probabilities of the composite components (E1 and E2) and the correlation between them in terms of Pearson's correlation coefficient.

Usage

prob_cbe(p_e1, p_e2, rho)

Arguments

p_e1	numeric parameter, probability of the event E1
p_e2	numeric parameter, probability of the event E2
rho	numeric parameter, Pearson's correlation between E1 and E2

Details

The input parameters stand for the probability of the composite components and Pearson's correlation between the two components. Note that Pearson's correlation takes values between two bounds that depend on the probabilities p0_e1 and p0_e2. To calculate the correlation bounds you can use the R functions lower_corr and upper_corr, available in this package.

Value

Returns the probability of the composite endpoint (E1 or E2).

References

Bofill Roig, M., & Gomez Melis, G. (2019). A new approach for sizing trials with composite binary endpoints using anticipated marginal values and accounting for the correlation between components. Statistics in Medicine, 38(11), 1935-1956. https://doi.org/10.1002/sim.8092

Examples

CompAREdesign::prob_cbe(p_e1=0.1, p_e2=0.2, rho=0)

---

Sample size for composite binary endpoints

Description

This function calculates the required sample size for trials with a composite binary endpoint as primary endpoint. The primary endpoint is assumed to be a composite binary endpoint formed by a combination of two events (E1 and E2). The sample size is computed to evaluate differences between two groups in terms of the risk difference, risk ratio or odds ratio. The sample size is calculated on the basis of anticipated information on the composite components and the correlation between them.

Usage

samplesize_cbe(
  p0_e1,
  p0_e2,
  eff_e1,
  effm_e1,
  eff_e2,
  effm_e2,
  effm_ce = "diff",
  rho,
  alpha = 0.05,
  beta = 0.2,
  unpooled = TRUE
)

Arguments

p0_e1	numeric parameter, probability of occurrence E1 in the control group
p0_e2	numeric parameter, probability of occurrence E2 in the control group
eff_e1	numeric parameter, anticipated effect for the composite component E1
effm_e1	Effect measure used for the event E1 (effm_e1 = "diff" for difference of proportions, effm_e1 = "rr" for risk ratio, effm_e1 = "or" for odds ratio)
eff_e2	numeric parameter, anticipated effect for the composite component E2
effm_e2	Effect measure used for the event E2 (effm_e2 = "diff" for difference of proportions, effm_e2 = "rr" for risk ratio, effm_e2 = "or" for odds ratio)
effm_ce	Effect measure used for the composite endpoint (effm_ce = "diff" for difference of proportions, effm_ce = "rr" for risk ratio, effm_ce = "or" for odds ratio)
rho	numeric parameter, Pearson's correlation between the two events E1 and E2
alpha	Type I error
beta	Type II error
unpooled	Variance estimate used for the sample size calculation ("TRUE" for unpooled variance estimate, and "FALSE" for pooled variance estimate).

Details

The input parameters stand for the probability of the composite components and Pearson's correlation between the two components. Note that Pearson's correlation takes values between two bounds that depend on the probabilities p0_e1 and p0_e2. To calculate the correlation bounds you can use the R functions lower_corr and upper_corr, available in this package.

Value

Return the total sample size for composite binary endpoints based on the anticipated values of the composite components and the association between them in terms of Pearson's correlation.

References

Bofill Roig, M., & Gomez Melis, G. (2019). A new approach for sizing trials with composite binary endpoints using anticipated marginal values and accounting for the correlation between components. Statistics in Medicine, 38(11), 1935-1956. https://doi.org/10.1002/sim.8092

---

Sample size for composite time to event endpoints

Description

This function calculates the required sample size for trials with a composite time to event endpoint as primary endpoint. The primary endpoint is assumed to be a composite time to event endpoint formed by a combination of two events (E1 and E2). The sample size is computed to evaluate differences between two groups based on the log rank test. The sample size is calculated on the basis of anticipated information on the composite components and the correlation between them.

Usage

samplesize_tte(
  p0_e1,
  p0_e2,
  HR_e1,
  HR_e2,
  beta_e1 = 1,
  beta_e2 = 1,
  case,
  copula = "Frank",
  rho = 0.3,
  rho_type = "Spearman",
  alpha = 0.05,
  power = 0.8,
  ss_formula = "schoenfeld",
  subdivisions = 50,
  plot_print = FALSE,
  plot_save = FALSE
)

Arguments

p0_e1	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E1
p0_e2	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E2
HR_e1	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E1
HR_e2	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E2
beta_e1	numeric positive parameter, shape parameter ($\beta_1$) for a Weibull distribution for the endpoint E1 in the control group. See details for more info.
beta_e2	numeric positive parameter, shape parameter ($\beta_2$) for a Weibull distribution for the endpoint E2 in the control group. See details for more info.
case	integer parameter in {1,2,3,4}: (1) none of the endpoints is death; (2) endpoint 2 is death; (3) endpoint 1 is death; (4) both endpoints are death by different causes.
copula	character indicating the copula to be used: "Frank" (default), "Gumbel" or "Clayton". See details for more info.
rho	numeric parameter between -1 and 1, Spearman's correlation coefficient o Kendall Tau between the marginal distribution of the times to the two events E1 and E2. See details for more info.
rho_type	character indicating the type of correlation to be used: "Spearman" (default) or "Kendall". See details for more info.
alpha	numeric parameter. The probability of type I error. By default $\alpha=0.05$
power	numeric parameter. The power to detect the treatment effect. By default $1-\beta=0.80$
ss_formula	character indicating the formula to be used for the sample size calculation on the single components: 'schoenfeld' (default) or 'freedman'
subdivisions	integer parameter greater than or equal to 10. Number of points used to plot the sample size according to correlation. The default is 50. Ignored if plot_print=FALSE and plot_save=FALSE.
plot_print	logical indicating if the sample size according to the correlation should be displayed. The default is FALSE
plot_save	logical indicating if the plot of sample size according to the correlation is stored for future customization. The default is FALSE

Details

Some parameters might be difficult to anticipate, especially the shape parameters of Weibull distributions and those referred to the relationship between the marginal distributions. For the shape parameters (beta_e1, beta_e2) of the Weibull distribution, we recommend to use $\beta_j=0.5$, $\beta_j=1$ or $\beta_j=2$ if a decreasing, constant or increasing rates over time are expected, respectively. For the correlation (rho) between both endpoints, generally a positive value is expected as it has no sense to design an study with two endpoints negatively correlated. We recommend to use $\rho=0.1$, $\rho=0.3$ or $\rho=0.5$ for weak, mild and moderate correlations, respectively. For the type of correlation (rho_type), although two different type of correlations are implemented, we recommend the use of the Spearman's correlation. In any case, if no information is available on these parameters, we recommend to use the default values provided by the function.

The user can choose between the two most common formulae (Schoenfeld and Freedman) for the sample size calculation for the single components. Schoenfeld formula always be used for the composite endpoint. Both Freedman's and Schoenfeld's formulas are nearly correct when the number of events, is large and the groups are balanced. Schoenfeld's formula generally yields a lower required number of events. From a parsimonious perspective, Schoenfeld's formula is preferable when minimizing the sample size is the main criterion.

Value

A list containing the following components:

ss_E1

Total sample size (both groups) for a trial using endpoint 1 as primary endpoint

ss_E2

Total sample size (both groups) for a trial using endpoint 2 as primary endpoint

ss_Ec

Total sample size (both groups) for a trial using composite endpoint as primary endpoint

In addition, if plot_save=TRUE an object of class ggplot with the sample size for composite endpoint according to correlation is stored in the list.

References

Friedman L.M., Furberg C.D., DeMets D.L. Fundamentals of Clinical Trials. 3rd ed. New York: Springer; 1998. Cortés Martínez, J., Geskus, R.B., Kim, K. et al. Using the geometric average hazard ratio in sample size calculation for time-to-event data with composite endpoints. BMC Med Res Methodol 21, 99 (2021). https://doi.org/10.1186/s12874-021-01286-x

Examples

samplesize_tte(p0_e1   = .59, p0_e2   = .74, 
               HR_e1   = .91, HR_e2   = .77, 
               beta_e1 = 1,   beta_e2 = 2, 
               case    = 3,   rho     = .5,
               copula  = 'Frank', rho_type   = 'Spearman',
               plot_print = FALSE, plot_save = FALSE)

---

Simulation of binary composite endpoints

Description

This simulates two-arm randomised controlled trials with binary composite endpoints. The composite endpoint is assumed to be an endpoint formed by a combination of two events (E1 and E2).

Usage

simula_cbe(p0_e1, p0_e2, eff_e1, effm_e1, eff_e2, effm_e2, rho, samplesize)

Arguments

p0_e1	numeric parameter, probability of occurrence E1 in the control group
p0_e2	numeric parameter, probability of occurrence E2 in the control group
eff_e1	numeric parameter, anticipated effect for the composite component E1
effm_e1	Effect measure used for the event E1 (effm_e1 = "diff" for difference of proportions, effm_e1 = "rr" for risk ratio, effm_e1 = "or" for odds ratio)
eff_e2	numeric parameter, anticipated effect for the composite component E2
effm_e2	Effect measure used for the event E2 (effm_e2 = "diff" for difference of proportions, effm_e2 = "rr" for risk ratio, effm_e2 = "or" for odds ratio)
rho	numeric parameter, Pearson's correlation between the two events E1 and E2
samplesize	sample size per arm

Details

The input parameters stand for the probability of the composite components and Pearson's correlation between the two components. Note that Pearson's correlation takes values between two bounds that depend on the probabilities p0_e1 and p0_e2. To calculate the correlation bounds you can use the R functions lower_corr and upper_corr, available in this package.

Value

Simulated data

---

Simulation of composite time-to-event endpoints

Description

This function simulates time-to-event components and their pertinent composite endpoint via copulas.

Usage

simula_tte(
  p0_e1,
  p0_e2,
  HR_e1,
  HR_e2,
  beta_e1 = 1,
  beta_e2 = 1,
  case,
  copula = "Frank",
  rho = 0.3,
  rho_type = "Spearman",
  followup_time = 1,
  sample_size
)

Arguments

p0_e1	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E1
p0_e2	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E2
HR_e1	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E1
HR_e2	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E2
beta_e1	numeric positive parameter, shape parameter ($\beta_1$) for a Weibull distribution for the endpoint E1 in the control group. See details for more info.
beta_e2	numeric positive parameter, shape parameter ($\beta_2$) for a Weibull distribution for the endpoint E2 in the control group. See details for more info.
case	integer parameter in {1,2,3,4}: (1) none of the endpoints is death; (2) endpoint 2 is death; (3) endpoint 1 is death; (4) both endpoints are death by different causes.
copula	character indicating the copula to be used: "Frank" (default), "Gumbel" or "Clayton". See details for more info.
rho	numeric parameter between -1 and 1, Spearman's correlation coefficient o Kendall Tau between the marginal distribution of the times to the two events E1 and E2. See details for more info.
rho_type	character indicating the type of correlation to be used: "Spearman" (default) or "Kendall". See details for more info.
followup_time	numeric parameter indicating the maximum follow up time (in any unit). Default is 1.
sample_size	sample size for each arm (treated and control)

Details

If sample_size is not an integer, it is rounded to the nearest integer.

Value

A data.frame with 7 colums:

time_e1

time to event for endpoint 1

status_e1

The status indicator of endpoint 1, 0=censored, 1=event

time_e2

time to event for endpoint 2

status_e2

The status indicator of endpoint 2, 0=censored, 1=event

time_ce

time to event for composite endpoint

status_ce

The status indicator of the composite endpoint, 0=censored, 1=event

treated

0 if control arm and 1, otherwise

Examples

# Simulate 10 times and censoring indicators for each arm
simula_tte(p0_e1   = .59, p0_e2   = .74, 
           HR_e1   = .91, HR_e2   = .77, 
           beta_e1 = 1,   beta_e2 = 2, 
           case    = 3,   rho     = .5,
           copula  = 'Frank', rho_type  = 'Spearman',
           sample_size = 10, followup_time = 2)

---

Survival function for composite time-to-event endpoints

Description

It provides the survival function for time-to-event composite outcomes. The composite endpoint is assumed to be a time-to-event endpoint formed by a combination of two events (E1 and E2). The effect size is calculated on the basis of anticipated information on the composite components and the correlation between them. Marginal distributions are assumed weibull for both endpoints.

Usage

surv_tte(
  p0_e1,
  p0_e2,
  HR_e1,
  HR_e2,
  beta_e1 = 1,
  beta_e2 = 1,
  case,
  copula = "Frank",
  rho = 0.3,
  rho_type = "Spearman",
  followup_time = 1,
  plot_print = TRUE,
  plot_save = FALSE
)

Arguments

p0_e1	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E1
p0_e2	numeric parameter between 0 and 1, expected proportion of observed events for the endpoint E2
HR_e1	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E1
HR_e2	numeric parameter between 0 and 1, expected cause specific hazard Ratio the endpoint E2
beta_e1	numeric positive parameter, shape parameter ($\beta_1$) for a Weibull distribution for the endpoint E1 in the control group. See details for more info.
beta_e2	numeric positive parameter, shape parameter ($\beta_2$) for a Weibull distribution for the endpoint E2 in the control group. See details for more info.
case	integer parameter in {1,2,3,4}: (1) none of the endpoints is death; (2) endpoint 2 is death; (3) endpoint 1 is death; (4) both endpoints are death by different causes.
copula	character indicating the copula to be used: "Frank" (default), "Gumbel" or "Clayton". See details for more info.
rho	numeric parameter between -1 and 1, Spearman's correlation coefficient o Kendall Tau between the marginal distribution of the times to the two events E1 and E2. See details for more info.
rho_type	character indicating the type of correlation to be used: "Spearman" (default) or "Kendall". See details for more info.
followup_time	numeric parameter indicating the maximum follow up time (in any unit). Default is 1.
plot_print	logical indicating if the survival curves should be displayed. The default is TRUE
plot_save	logical indicating if the plot of the survival curve for composite endpoint is stored for future customization. The default is FALSE

Details

Some parameters might be difficult to anticipate, especially the shape parameters of Weibull distributions and those referred to the relationship between the marginal distributions. For the shape parameters (beta_e1, beta_e2) of the Weibull distribution, we recommend to use $\beta_j=0.5$, $\beta_j=1$ or $\beta_j=2$ if a decreasing, constant or increasing rates over time are expected, respectively. For the correlation (rho) between both endpoints, generally a positive value is expected as it has no sense to design an study with two endpoints negatively correlated. We recommend to use $\rho=0.1$, $\rho=0.3$ or $\rho=0.5$ for weak, mild and moderate correlations, respectively. For the type of correlation (rho_type), although two different type of correlations are implemented, we recommend the use of the Spearman's correlation. In any case, if no information is available on these parameters, we recommend to use the default values provided by the function.

Value

For each group, if plot_print=TRUE, the function returns a plot of the survival functions for composite endpoint as well as the plots of the survival function for each component.

Examples

surv_tte(p0_e1   = .59, p0_e2   = .74, 
         HR_e1   = .91, HR_e2   = .77, 
         beta_e1 = 1,   beta_e2 = 2, 
         case    = 3,   rho     = .5,
         copula  = 'Frank', rho_type   = 'Spearman',
         plot_print = TRUE, plot_save = FALSE,
         followup_time = 2)

---

Upper bound for Pearson's Correlation

Description

Pearson's correlation between two binary outcomes takes values between two bounds defined according to the probabilities of the binary outcomes. This function calculates the upper bound of the correlation based on the probabilities of two binary outcomes.

Usage

upper_corr(p_e1, p_e2)

Arguments

p_e1	numeric parameter, probability of the event E1
p_e2	numeric parameter, probability of the event E2

Details

upper_corr returns a numeric value between 0 and 1.

Value

Returns the maximum value that the correlation between the two outcomes can take.

Examples

CompAREdesign::upper_corr(p_e1=0.3, p_e2=0.6)

---