Package 'smiles'

smiles: Sequential Method In Leading Evidence Synthesis

Description

The purpose of R-package smiles is to provide a useful collection of functions designed to apply sequential method in data synthesis and evidence evaluation. This package is developed based on meta (version 7.0-0) in R version 4.2.2 (2022-10-31 ucrt).

Details

Current version consists of three functions, including a main function of sequential analysis (i.e. DoTSA) and a visualization function of sequential analysis, (i.e. PlotCoRNET).

---

Trial sequential analysis.

Description

DoTSA() is a function for conducting trial sequential analysis.

Usage

DoTSA(
  data = NULL,
  source = NULL,
  time = NULL,
  n = NULL,
  es = NULL,
  se = NULL,
  r1 = NULL,
  m1 = NULL,
  sd1 = NULL,
  n1 = NULL,
  r2 = NULL,
  m2 = NULL,
  sd2 = NULL,
  n2 = NULL,
  group = c("Group 1", "Group 2"),
  ref = 2,
  prefer = "small",
  measure = "ES",
  model = "random",
  method = "DL",
  pooling = "IV",
  trnsfrm = "logit",
  poolProp = "IV",
  alpha = 0.05,
  beta = 0.2,
  PES = NULL,
  RRR = NULL,
  PV = "post-hoc",
  adjust = "D2",
  plot = FALSE,
  id = FALSE,
  invert = FALSE,
  smooth = FALSE,
  SAP = FALSE,
  BSB = FALSE
)

Arguments

data	DATAFRAME consists of relevant information.
source	CHARACTER for labeling the included data sets.
time	NUMERIC values of time sequence.
n	INTEGER values of sample sizes.
es	NUMERIC values of effect sizes.
se	NUMERIC values of standard errors for the effect sizes.
r1	INTEGER values of observed events in group 1 in the included data.
m1	NUMERIC values of estimated means in group 1 in the included data.
sd1	NUMERIC values of standard deviations in group 1 in the included data.
n1	INTEGER values of sample sizes in group 1 in the included data.
r2	INTEGER values of observed events in group 2 in the included data.
m2	NUMERIC values of estimated means in group 2 in the included data.
sd2	NUMERIC values of standard deviations in group 2 in the included data.
n2	INTEGER values of sample sizes in group 2 in the included data.
group	CHARACTER for labeling two groups.
ref	NUMERIC values of 1 or 2 for indicating group 1 or 2 as reference.
prefer	CHARACTER of "small" and "large" for indicating which direction is beneficial effect in statistic test.
measure	CHARACTER for indicating which statistic measure should be used.
model	CHARACTER of "random" and "fixed" for indicating whether to use random-effects model or fixed-effect model.
method	CHARACTER for indicating which estimator should be used in random-effects model. In addition to the default "DL" method, the current version also supports "REML" and "PM" methods for calculating heterogeneity estimator.
pooling	CHARACTER for indicating which method has to be used for pooling binary data. Besides, current version also supports "MH" and "Peto" for binary data pooling.
trnsfrm	CHARACTER for indicating which method for transforming pooled proportion. Current version supports "none", "logit", "log", "arcsine", and "DAT" for the transformation.
poolProp	CHARACTER for indicating which method has to be used for pooling proportion. Current version supports "IV" and "GLMM" for the data pooling.
alpha	NUMERIC value between 0 to 1 for indicating the assumed type I error.
beta	NUMERIC value between 0 to 1 for indicating the assumed type II error.
PES	NUMERIC value for indicating the presumed meaningful effect size.
RRR	NUMERIC value between 0 and 1 for indicating the presumed relative risk reduction. This parameter only works for dichotomous outcome by replacing parameter PES.
PV	NUMERIC value for indicating the presumed variance of the meaningful effect size. Current version allows a numeric value, "post-hoc", and "PES" based on different considerations.
adjust	CHARACTER for indicating how to adjust optimal information size. Current version consists of "none", "D2", "I2", "CHL", "CHM", and "CHH" for the adjustment.
plot	LOGIC value for indicating whether to illustrate alpha-spending monitoring plot.
id	LOGIC value for indicating whether to label each data source.
invert	LOGIC value for indicating whether to invert plot.
smooth	LOGIC value for indicating whether to smooth error boundaries.
SAP	LOGIC value for indicating whether to show sequential-adjusted power.
BSB	LOGIC value for indicating whether to illustrate beta-spending boundaries.

Details

1. Basic information for the function DoTSA(): DoTSA() supports sequential analysis of aggregate data synthesis based on head-to-head comparison using either binary or continuous data in each group. Minimum information for the function DoTSA() encompasses a data set of study-level data, and information for analysis settings in terms of time sequence, presumed meaningful effect size, and presumed variance of the meaningful effect size. Operative points of using function DoTSA() are listed below:

1.1. Parameter data should be used for assigning a data set. 1.2. Study-level data have to be assigned according to outcome type: 1.2.1. For dichotomous outcome: Parameter n1 and n2 should be defined with parameter r1 and r2. 1.2.2. For continuous outcome: parameter n1 and n2 should be defined with parameter m1, sd1, m2, sd2. 1.3. Parameter source, time, PES, and PV are required for conducting sequential analysis. Other parameters are auxiliary.

1. Default in the function DoTSA() Certain defaults have been elucidated in the introductory section about the parameters, but some of them need to be elaborated upon due to their complexity.

2.1. Default on the parameter measure is "ES" that automatically uses risk ratio ("RR") for binary outcome and mean difference ("MD") for continuous outcome respectively. Argument "OR" and "SMD" can be used for the parameter measure when original analysis pools data based on odds ratio or standardized mean difference.

2.2. Default on the parameter method is "DL" for applying DerSimonian-Laird heterogeneity estimator in the original pooled analysis. Other eligible arguments for the parameter are "REML" for restricted maximum-likelihood estimator, "PM" for Paule-Mandel estimator, "ML" for maximum-likelihood estimator, "HS" for Hunter-Schmidt estimator, "SJ" for Sidik-Jonkman estimator, "HE" for Hedges estimator, and "EB" for empirical Bayes estimator.

2.3. Default on the parameter pooling is "IV" for applying inverse variance weighting method. Other commonly-used and eligible arguments for the parameter are "MH" for Mantel-Haenszel method and "Peto" for pooling data using Peto method. The arguments "MH" and "Peto" are exclusively available for binary outcomes, while the argument "IV" will be automatically applied in the case of continuous outcomes.

2.4. Default on the parameter adjust is "D2" for adjusting required information size (RIS) based on diversity (D-squared statistics). Other eligible arguments for the parameter are "None" for the RIS without adjustment, "I2" for adjusted RIS based on I-squared statistics, "CHL" for adjusted RIS based on low heterogeneity by multiplying 1.33, "CHM" for adjusted RIS by multiplying 2 due to moderate heterogeneity, and "CHL" for adjusted RIS by multiplying 4 due to high heterogeneity.

Value

DoTSA() returns a summary on the result of sequential analysis, and can be stored as an object in DoTSA class. Explanations of returned information are listed as follows:

studies	Numbers of studies included in the sequential analysis.
AIS	Acquired information size refers to the total sample size in the sequential analysis.
alpha	A numeric value of type I error for the sequential analysis.
beta	A numeric value of type II error for the sequential analysis.
PES	A numeric value of presumed meaningful effect size for the sequential analysis.
RRR	A numeric value of relative risk reduction.
variance	A numeric value of presumed variance of the meaningful effect size for the sequential analysis.
diversity	A numeric value to show diversity in the pooled analysis.
AF	A numeric value of adjustment factor.
RIS.org	A numeric value for required information size without adjustment.
RIS.adj	A numeric value for adjusted required information size.
frctn	A vector of fraction of each study included in the sequential analysis.
weight	A vector of weight of each study included in the sequential analysis.
es.cum	A vector of cumulative effect size in the sequential analysis.
se.cum	A vector of standard error for the cumulative effect size in the sequential analysis.
zval.cum	A vector of cumulative z-value in the sequential analysis.
asb	A data frame of alpha-spending values for each study.
aslb	A numeric value for lower alpha-spending boundary.
asub	A numeric value for upper alpha-spending boundary.

Author(s)

Enoch Kang

References

Jennison, C., & Turnbull, B. W. (2005). Meta-analyses and adaptive group sequential designs in the clinical development process. Journal of biopharmaceutical statistics, 15(4), 537–558. https://doi.org/10.1081/BIP-200062273.

Wetterslev, J., Jakobsen, J. C., & Gluud, C. (2017). Trial sequential analysis in systematic reviews with meta-analysis. BMC medical research methodology, 17(1), 1-18.

NCSS Statistical Software (2023). Group-sequential analysis for two proportions. In PASS Documentation. Available online: https://www.ncss.com/wp-content/themes/ncss/pdf/Procedures/NCSS/Group-Sequential_Analysis_for_Two_Proportions.pdf

See Also

PlotCoRNET

Examples

## Not run:
# 1. Import a dataset of study by Fleiss (1993)
library(meta)
data("Fleiss1993bin")

# 2. Perform trial sequential analysis
DoTSA(Fleiss1993bin, study, year,
      r1 = d.asp, n1 = n.asp,
      r2 = d.plac, n2 = n.plac,
      measure = "RR", RRR = 0.2,
      group = c("Aspirin", "Control"))

## End(Not run)

---

Plot of Continuous Restriction for Noting Error Thresholds

Description

PlotCoRNET() is a function for plotting Continuous Restriction for Noting Error Thresholds. In other words, it returns sequential monitoring and interim line and edge.

Usage

PlotCoRNET(
  object = NULL,
  sclAxsX = "sample",
  txtTtl = NULL,
  group = NULL,
  lgcZone = FALSE,
  lgcLblStdy = FALSE,
  lgcSAP = FALSE,
  lgcInvert = FALSE,
  lgcSmooth = FALSE,
  szFntTtl = 1.8,
  szFntTtlX = 1.2,
  szFntTtlY = NULL,
  szFntAxsX = 0.8,
  szFntAxsY = 0.8,
  szFntLgnd = 0.7,
  szFntLblY = 1.2,
  szFntStdy = 0.8,
  szFntRIS = 0.8,
  szFntAIS = 0.8,
  szPntStdy = 1,
  szPntASB = 0.8,
  szLn0 = 1,
  szLnSig = 1,
  szLnZCum = 2,
  szLnASB = 1,
  szLnRIS = 1,
  typPntStdy = NULL,
  typPntASB = NULL,
  typLn0 = 1,
  typLnSig = 2,
  typLnZCum = 1,
  typLnASB = 3,
  typLnRIS = 2,
  clrTtl = "black",
  clrTtlX = "black",
  clrTtlY = "black",
  clrAxsX = "black",
  clrAxsY = "black",
  clrLgnd = "black",
  clrLblY = "black",
  clrLblStdy = "black",
  clrLblRIS = "black",
  clrLblAIS = "black",
  clrPntStdy = "gray25",
  clrPntASB = "none",
  clrLn0 = "gray25",
  clrLnSig = "gray",
  clrLnZCum = "blue4",
  clrLnASB = "red4",
  clrLnRIS = "red4",
  anglStdy = 30,
  BSB = FALSE
)

Arguments

object	OBJECT in DoTSA class that is an output of trial sequential analysis using function DoTSA().
sclAxsX	CHARACTER for indicating unit of scale on axis X.
txtTtl	CHARACTER for user-defined main title on the trial sequential analysis plot.
group	CHARACTER for labeling two groups.
lgcZone	LOGIC value for indicating whether to show zones.
lgcLblStdy	LOGIC value for indicating whether to label each data source.
lgcSAP	LOGIC value for indicating whether to show sequential-adjusted power.
lgcInvert	LOGIC value for indicating whether to invert plot.
lgcSmooth	LOGIC value for indicating whether to smooth error boundaries.
szFntTtl	NUMERIC value for indicating font size of main title.
szFntTtlX	NUMERIC value for indicating font size of title on axis X.
szFntTtlY	NUMERIC value for indicating font size of title on axis Y.
szFntAxsX	NUMERIC value for indicating font size of scale on axis X.
szFntAxsY	NUMERIC value for indicating font size of scale on axis Y.
szFntLgnd	NUMERIC value for indicating font size of legend.
szFntLblY	NUMERIC value for indicating font size of the label of "Cumulative z-score" on axis Y.
szFntStdy	NUMERIC value(s) for indicating font size(s) of the label(s) of each data source.
szFntRIS	NUMERIC value for indicating font size of the label of required information size.
szFntAIS	NUMERIC value for indicating font size of the label of acquired information size.
szPntStdy	NUMERIC value(s) for indicating size(s) of observed point(s).
szPntASB	NUMERIC value for indicating size of point(s) on alpha-spending boundaries.
szLn0	NUMERIC value for indicating width of null line.
szLnSig	NUMERIC value for indicating width of line for statistical significance.
szLnZCum	NUMERIC value for indicating width of line for cumulative z-score.
szLnASB	NUMERIC value for indicating width of line for alpha-spending boundaries.
szLnRIS	NUMERIC value for indicating width of line for required information size.
typPntStdy	NUMERIC value(s) between 1 to 5 for indicating type(s) of observed point(s). Symbols in the current version includes circle, square, diamond, triangle point-up, and triangle point down.
typPntASB	NUMERIC value between 1 to 5 for indicating type of point(s) on alpha-spending boundaries. Symbols in the current version includes circle, square, diamond, triangle point-up, and triangle point down.
typLn0	NUMERIC value for indicating type of null line.
typLnSig	NUMERIC value for indicating type of line for statistical significance.
typLnZCum	NUMERIC value for indicating type of line for cumulative z-score.
typLnASB	NUMERIC value for indicating type of line for alpha-spending boundaries.
typLnRIS	NUMERIC value for indicating type of line for required information size.
clrTtl	CHARACTER of a color name for main title.
clrTtlX	CHARACTER of a color name for title on axis X.
clrTtlY	CHARACTER of a color name for title on axis Y.
clrAxsX	CHARACTER of a color name for scale on axis X.
clrAxsY	CHARACTER of a color name for scale on axis Y.
clrLgnd	CHARACTER of a color name for legend.
clrLblY	CHARACTER of a color name for the label "Cumulative z-score" on axis Y.
clrLblStdy	CHARACTER of color name(s) for the label(s) of each data source.
clrLblRIS	CHARACTER of a color name for the label of required information size.
clrLblAIS	CHARACTER of a color name for the label of acquired information size.
clrPntStdy	CHARACTER of color name(s) for observed point(s) of data source.
clrPntASB	CHARACTER of a color name for point(s) on the alpha-spending boundaries.
clrLn0	CHARACTER of a color name for null line.
clrLnSig	CHARACTER of a color name for line of statistical significance.
clrLnZCum	CHARACTER of a color name for line of cumulative z-score.
clrLnASB	CHARACTER of a color name for line of alpha-spending boundaries.
clrLnRIS	CHARACTER of a color name for line of required information size.
anglStdy	NUMERIC value between 0 and 360 for indicating angle of data source.
BSB	LOGIC value for indicating whether to illustrate beta-spending boundaries.

Value

PlotCoRNET() returns a plot of trial sequential analysis.

Author(s)

Enoch Kang

References

Jennison, C., & Turnbull, B. W. (2005). Meta-analyses and adaptive group sequential designs in the clinical development process. Journal of biopharmaceutical statistics, 15(4), 537–558. https://doi.org/10.1081/BIP-200062273.

Wetterslev, J., Jakobsen, J. C., & Gluud, C. (2017). Trial sequential analysis in systematic reviews with meta-analysis. BMC medical research methodology, 17(1), 1-18.

NCSS Statistical Software (2023). Group-sequential analysis for two proportions. In PASS Documentation. Available online: https://www.ncss.com/wp-content/themes/ncss/pdf/Procedures/NCSS/Group-Sequential_Analysis_for_Two_Proportions.pdf

See Also

DoTSA

Examples

## Not run:
# 1. Import a dataset of study by Fleiss (1993)
library(meta)
data("Fleiss1993bin")

# 2. Perform trial sequential analysis
 output <- DoTSA(Fleiss1993bin, study, year,
                 r1 = d.asp, n1 = n.asp,
                 r2 = d.plac, n2 = n.plac,
                 measure = "RR", RRR = 0.2,
                 group = c("Aspirin", "Placebo"),
                 plot = TRUE)

# 3. Illustrate plot of trial sequential analysis
 PlotCoRNET(output)

## End(Not run)

---