---
title: "An overview on R-pakcage smiles"
output: 
  bookdown::html_document2:
    base_format: rmarkdown::html_vignette
    number_sections: true
vignette: >
  %\VignetteIndexEntry{An overview on R-pakcage smiles}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

<H3>
<span style = "color:blue">S</span>equential 
<span style = "color:blue">M</span>ethods 
<span style = "color:blue">I</span>n 
<span style = "color:blue">L</span>eading 
<span style = "color:blue">E</span>vidence 
<span style = "color:blue">S</span>ynthesis 
</H3>
[![Version](https://img.shields.io/badge/Version-0.1.0-blue.svg?logo=r&logoColor=skyblue)]
[![Date](https://img.shields.io/badge/Date-Aug.18.2024-blue.svg?logo=r&logoColor=skyblue)]
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-blue.svg?color=blue&label=Lifecycle&logo=r&logoColor=skyblue)](https://lifecycle.r-lib.org/articles/stages.html#stable)

\

# Prologue

The *smiles* R package is designed to make data synthesis and evidence evaluation easier. It offers a range of functions that simplify complex analysis processes, making them more accessible to both experienced professionals and newcomers. By emphasizing flexibility, ease of use, and clarity, *smiles* helps users better understand and engage with synthesized data. This broader engagement is crucial for navigating and interpreting complex evidence. To get started, simply call the library using the following syntax:

```{r}
library(smiles)
```

```{r setup, echo = FALSE, warning = FALSE, message = FALSE}
library(smiles)
library(meta)
```

\

# Focus & functions

Briefly, *smiles* currently focuses on **trial sequential analysis** that is a method to examine whether the evidence is firm with sufficiency of information size. Users can import their data and do the test and graphics using functions. The present package consists of two functions, including:

`DoTSA()` [![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg?color=grassgreen)](https://lifecycle.r-lib.org/articles/stages.html#stable): the main function of trial sequential analysis

`PlotCoRNET()` [![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg?color=grassgreen)](https://lifecycle.r-lib.org/articles/stages.html#stable): a visualization function of trial sequential analysis

\

## Trial sequential analysis {-}
Sequential analysis in evidence-based medicine is a statistical approach applied in clinical trials and meta-analyses to continually assess accumulating data, allowing for interim decisions on the effectiveness or safety of medical interventions ([Kang, 2021](#ref-Kang2021); [Jennison & Turnbull, 2005](#ref-Jennison2005); [Wetterslev et al., 2017](#ref-Wetterslev2017); [Wetterslev et al., 2008](#ref-Wetterslev2008)). In contrast to traditional methods that wait for all data to be collected, sequential analysis enables periodic assessments during a trial. This method is especially valuable when ongoing assessment is ethically or practically necessary. It seeks to balance the need for robust statistical inference with the ethical duty to ensure participant safety and prompt decision-making that can influence clinical practice. Traditional sequential analysis is proposed for prospective design in terms of trial, and could be adapted for prospective meta-analysis (PMA). Proper planning and pre-specification in study protocols are crucial for maintaining the integrity of sequential analysis ([Thomas et al., 2019](#ref-Thomas2019)). In other words, it is generally discouraged to employ sequential analysis methodologies for conventional meta-analysis (CMA) lacking pre-established parameters within the study protocol. However, it is imperative to acknowledge the persistent relevance of sequential methodologies in facilitating the assessment of error control mechanisms by researchers and clinicians. In scenarios where relevant parameters for sequential analysis remain unspecified, conducting observed sequential analysis serves as a valuable strategy for evaluating the efficacy of error control measures within a synthesis.

### Fundamental method of trial sequential analysis {-}
Sequential method has the capability to manage the overall Type I error in clinical trials and cumulative meta-analyses through the utilization of an alpha spending function, exemplified by the approach introduced by [O'Brien & Fleming (1979)](#ref-O'Brien1979). Based on required sample size (*RSS*) or required information size (*RIS*), sequential analysis applies the alpha spending function to allocate less significance level to early interim analyses, demanding more substantial evidence for declaring statistical significance. Critical boundaries for significance are determined by this function, becoming less stringent as more data accumulates. Sequential analysis uses these boundaries to monitor effects at each interim analysis, declaring statistical significance if the cumulative *Z*-score crosses them. This approach minimizes the risk of false positives in sequential analyses, where multiple interim analyses are conducted, while maintaining the ability to detect true effects. 

Therefor, the essentials of sequential meta-analysis encompass various elements including study time, sample size, and cumulative *Z*-scores derived from cumulative meta-analysis following a temporal order. Additionally, integral to this analysis are the anticipated effects of intervention or exposure, which are either predetermined or established through prior estimates, along with their respective variances. Moreover, the formulation accounts for predefined probabilities associated with Type I error (denoted as $\alpha$) and Type II error (denoted as $\beta$). Leveraging this comprehensive set of parameters, particularly the anticipated effects and their associated variances in conjunction with $\alpha$ and $\beta$, this methodology facilitates the computation of the *RIS* and the establishment of alpha-spending monitoring boundaries. By charting the information size axis, the analysis offers a comprehensive visualization of the cumulative *Z*-scores and the accompanying alpha-spending monitoring boundaries ([Wetterslev et al., 2008](#ref-Wetterslev2008); [Wetterslev et al., 2009](#ref-Wetterslev2009); [Wetterslev et al., 2017](#ref-Wetterslev2017)).

Within the realm of sequential method, the concept of the *RIS* holds paramount significance as it serves as the cornerstone for establishing spending monitoring boundaries, necessitated by adjustments to accommodate multiple interim analyses ([Wetterslev et al., 2017](#ref-Wetterslev2017)). Essentially, sequential methods encompass considerations pertinent to sample size determination, albeit employing an approach divergent from conventional methodologies employed in hypothesis testing or estimation. The determination of the information size, delineating the *RSS*, hinges crucially upon various parameters including the anticipated effect size, statistical power, significance level, and any requisite adjustments tailored for multiple testing scenarios. Conventionally, the determination of the *RSS* encompasses an assessment of intervention or exposure effects, their variance, as well as the predefined probabilities associated with Type I error ($\alpha$) and Type II error ($\beta$). The formula governing the calculation of the *RSS* is as follows:

\begin{equation}
RSS = 4 \times (Z_{1-\alpha/2} + Z_{1 - \beta})^2 \times \frac{\sigma^2} {\delta^2}
(\#eq:eq-RRS)
\end{equation}

Where 
:   $\alpha$ represents the predefined overall probabilities of false positive. \
    $\beta$ represents the predefined overall probabilities of false negative. \
    $\delta$ refers to the assumed effect, representing either the minimal or expected meaningful effect. \
    $\sigma^2$ refers to the variance that associated with the assumed effect.
    
\

In the context of dichotomous outcomes, the parameter $\delta$ can be substituted with the effect size that a trial aims to address, denoted by $\mu$, derived from the difference in proportions between the control and experimental groups, represented by $P_{control} - P_{experiment}$. Here, $P_{control}$ and $P_{experiment}$ signify the proportions of observed events in the control and experimental groups, respectively. The variance $\sigma^2$ is computed as $P_{average} \times (1 - P_{average})$, where $P_{average}$ is derived from $(P_{control} + P_{experiment}) / 2$ ([Wetterslev et al., 2017](#ref-Wetterslev2017)). For continuous outcomes, the *RSS* can be determined as follows:

\begin{equation}
RSS_{continuous} = 4 \times (Z_{1-\alpha/2} + Z_{1 - \beta})^2 \times \frac{MD^2} {SD^2}
(\#eq:eq-RRS-continuous)
\end{equation}

Where 
:   $\alpha$ represents the predefined overall probabilities of false positive. \
    $\beta$ represents the predefined overall probabilities of false negative. \
    $MD$ refers to the assumed mean difference between two groups. \
    $SD$ refers to the standard deviation that associated with the assumed mean difference. 
    
\

Based on the basic formula for calculating *RSS*, *RIS* in sequential method could be calculated by using assumed pooled effect and the variance that associated with the assumed pooled effect ([Wetterslev et al., 2017](#ref-Wetterslev2017)). Thus, the formula for the calculation of the *RIS* for meta-analysis in fixed-effect model is as follows:

\begin{equation}
RIS_{fixed} = 4 \times (Z_{1-\alpha/2} + Z_{1 - \beta})^2 \times \frac{V_{fixed}} {\theta^2}
(\#eq:eq-RIS-fixed)
\end{equation}

Where 
:   $\alpha$ represents the predefined overall probabilities of false positive. \
    $\beta$ represents the predefined overall probabilities of false negative. \
    $\theta$ refers to the assumed pooled effect, representing either the minimal or expected meaningful effect. \
    $V_{fixed}$ refers to the variance that associated with the assumed pooled effect in fixed-effect model. 
    
\

In meta-analysis employing the random-effects model, the calculation of the *RIS* follows a similar formula, but with a substitution of the variance associated with the assumed pooled effect by the variance specific to the random-effects model. *RIS* for meta-sequential analysis in random-effects model can be denoted as $RIS_{random}$. For a conservative estimation of the *RIS* in meta-analyses featuring heterogeneity, it is advisable to incorporate a heterogeneity correction factor ([Wetterslev et al., 2008](#ref-Wetterslev2008)), also referred to as the Adjusted Factor (*AF*) in Trial Sequential Analysis (TSA) ([Wetterslev et al., 2009](#ref-Wetterslev2009); [Wetterslev et al., 2017](#ref-Wetterslev2017)). Obviously, the calculation of the heterogeneity correction factor is inherently tied to the heterogeneity statistics. The I-squared statistic (denoted as $I^2$) is particularly suited for this purpose, serving as a widely utilized measure for quantifying and assessing heterogeneity ([Higgins & Thompson, 2002](#ref-Higgins2002)). $I^2$-based *AF* (denoted as $AF_{I^2}$) can be derived from the formula as follow:

\begin{equation}
AF_{I^2} = \frac{1} {(1 - I^2)}
(\#eq:eq-AF-I2)
\end{equation}

\

However, $I^2$ may provide misleading estimates due to uncertainties in the sampling error could introduce bias or inaccuracies into the analysis. Alternative measures or adjustments that are less susceptible to issues related to sampling error estimation should be considered ([Wetterslev et al., 2009](#ref-Wetterslev2009)). Diversity (denoted as $D^2$) has been proposed as a pivotal parameter in the computation of *AF* for the *RIS* in random-effects meta-analysis ([Wetterslev et al., 2009](#ref-Wetterslev2009); [Wetterslev et al., 2017](#ref-Wetterslev2017)). It is derived from the variances observed in both the random-effects model ($V_{random}$) and the fixed-effect model ($V_{fixed}$). The formula for calculating $D^2$ is as follows:

\begin{equation}
D^2 = \frac{(V_{random} - V_{fixed})} {V_{random}}
(\#eq:eq-D2)
\end{equation}

\

Then, the calculation of $D^2$-based *AF* (denoted as $AF_{D^2}$) is similar to the formula of $AF_{I^2}$ with replacement of $I^2$ by $D^2$. When addressing concerns regarding sampling error or bias, $AF_{D^2}$ offers notable advantages over $AF_{I^2}$ because $D^2$ operates without the prerequisite of assuming a typical sampling error (usually denoted as $\sigma^2$). Besides, it accurately mirrors the relative variance expansion resultant from the between-trial variance estimate, and exhibits a propensity to diminish as the estimate decreases, even when applied to identical study sets ([Wetterslev et al., 2009](#ref-Wetterslev2009)).

To provide a conservative estimation of the *RIS* for meta-analyses with heterogeneity, it is recommended to utilize an adjusted RIS. This can be achieved by multiplying $RIS_{random}$ by the *AF* ([Wetterslev et al., 2009](#ref-Wetterslev2009)). Subsequently, there are two the I-squared-adjusted information size (*HIS*) can be derived by further multiplying $RIS_{random}$ by $AF_{I^2}$. Similarly, the diversity-adjusted information size (DIS) is obtained by calculating $RIS_{random}$ multiplied by $AF_{D^2}$, as suggested by [Wetterslev et al. (2009)](#ref-Wetterslev2009).

\

# Step and example

The following steps and syntax demonstrate how user can carry out sequential analysis. Figure \@ref(fig:plot-sequential) sequential analysis plot. This demonstration serves as a guide for users intending to conduct a prospective meta-analysis with predefined parameters such as Type I error ($\alpha$), Type II error ($\beta$), presumed effect size (relative risk reduction, denoted as $RRR$, for dichotomous outcomes; mean difference, denoted as $MD$, for continuous outcomes), an estimate of the variability associated with the presumed effect. However, this demonstration may not be applicable for meta-analyses conducted without such pre-specified parameters.

\

<a id="step-1-DoTSA"></a>
**Step 1:** Import data (example of the study by Fleiss 1993)

``` {r, eval = FALSE}
library(meta)
data("Fleiss1993bin")
dataFleiss1993bin <- Fleiss1993bin
```

\

<a id="step-2-DoTSA"></a>
**Step 2:** Do trial sequential analysis

``` {r, eval = FALSE}
DoTSA(Fleiss1993bin, 
     source = study, 
     time = year,
     r1 = d.asp, 
     n1 = n.asp, 
     r2 = d.plac, 
     n2 = n.plac, 
     measure = "RR",
     PES = 0.1,
     RRR = 0.2,
     group = c("Aspirin", "Placebo"))
```

``` {r result-DoTSA, eval = TRUE, echo = FALSE, warning = FALSE, message = FALSE}
data("Fleiss1993bin")
dataFleiss1993bin <- Fleiss1993bin
DoTSA(Fleiss1993bin, 
     source = study, 
     time = year,
     r1 = d.asp, 
     n1 = n.asp, 
     r2 = d.plac, 
     n2 = n.plac, 
     measure = "RR",
     PES = 0.1,
     RRR = 0.2,
     group = c("Aspirin", "Placebo"))
```

\

<a id="step-3-DoTSA"></a>
**Step 3:** Visualize sequential analysis

``` {r, eval = FALSE}
DoTSA(Fleiss1993bin, 
     source = study, 
     time = year,
     r1 = d.asp, 
     n1 = n.asp, 
     r2 = d.plac, 
     n2 = n.plac, 
     measure = "RR",
     PES = 0.1,
     RRR = 0.2,
     group = c("Aspirin", "Placebo"),
     plot = TRUE)
```

``` {r plot-sequential, fig.cap = "An example for sequential analysis", eval = TRUE, echo = FALSE, warning = FALSE, message = FALSE, results = "hide", fig.height = 6, fig.width = 8, fig.align = "center", out.width = "100%"}
data("Fleiss1993bin")
dataFleiss1993bin <- Fleiss1993bin
DoTSA(Fleiss1993bin, 
     source = study, 
     time = year,
     r1 = d.asp, 
     n1 = n.asp, 
     r2 = d.plac, 
     n2 = n.plac, 
     measure = "RR",
     RRR = 0.2,
     group = c("Aspirin", "Placebo"),
     plot = TRUE)
```

\

**Optional step:** Modify CoRNET plot (example of the study by Fleiss 1993)

If users would like to modify the plot of trial sequential analysis, the users could store the output of function `DoTSA()` with argument `TRUE` for parameter `Plot` followed by putting the output into function `PlotCoRNET()` with relevant arguments.

\

<a id="step-2-PlotCoRNET"></a>
**An example:** to show colorful zone on the CoRNET plot with argument `TRUE` for parameter `lgcZone`

``` {r, eval = FALSE}
PlotCoRNET(output,
           lgcZone = TRUE,
           lgcLblStdy = TRUE,
           anglStdy = 60)
```

``` {r plot-CoRNET, fig.cap = "An example for illustrating colorful zones on trial sequential analysis", eval = TRUE, echo = FALSE, warning = FALSE, message = FALSE, results = "hide", fig.height = 8, fig.width = 8, fig.align = "center", out.width = "100%"}
data("Fleiss1993bin")
dataFleiss1993bin <- Fleiss1993bin
output <- DoTSA(Fleiss1993bin, 
     source = study, 
     time = year,
     r1 = d.asp, 
     n1 = n.asp, 
     r2 = d.plac, 
     n2 = n.plac, 
     measure = "RR",
     RRR = 0.2,
     group = c("Aspirin", "Placebo"),
     SAP = TRUE,
     plot = FALSE)

PlotCoRNET(output,
           lgcZone = TRUE,
           lgcLblStdy = TRUE,
           anglStdy = 60)
```

\

# Reference {-}

<a id="ref-Higgins2002"></a>
<p style="text-indent: -25px; margin-left: 25px;">
Higgins, J. P., & Thompson, S. G. (2002). Quantifying heterogeneity in a meta‐analysis. *Statistics in medicine, 21(11)*, 1539-1558. https://doi.org/10.1002/sim.1186
</p>

<a id="ref-Jennison2005"></a>
<p style="text-indent: -25px; margin-left: 25px;">
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
</p>

<a id="ref-Kang2021"></a>
<p style="text-indent: -25px; margin-left: 25px;">
Kang, H. (2021). Trial sequential analysis: novel approach for meta-analysis. *Anesthesia and Pain Medicine, 16(2)*, 138-150.  https://doi.org/10.17085/apm.21038
</p>

<a id="ref-O'Brien1979"></a>
<p style="text-indent: -25px; margin-left: 25px;">
O'Brien, P. C., & Fleming, T. R. (1979). A multiple testing procedure for clinical trials. *Biometrics, 35(3)*, 549-556. https://doi.org/10.2307/2530245
</p>

<a id="ref-Thomas2019"></a>
<p style="text-indent: -25px; margin-left: 25px;">
Thomas, J., Askie, L. M., Berlin, J. A., Elliott, J. H., Ghersi, D., Simmonds, M., Takwoingi, Y., Tierney, J. F., Higgins, J. P. T. (2019). Prospective approaches to accumulating evidence. In Higgins J. P. T., & Green, S., (Eds.), *Cochrane Handbook for Systematic Reviews of Interventions*. Chichester (UK): John Wiley & Sons. https://training.cochrane.org/handbook/archive/v6/chapter-22
</p>

<a id="ref-Wetterslev2008"></a>
<p style="text-indent: -25px; margin-left: 25px;">
Wetterslev, J., Thorlund, K., Brok, J., & Gluud, C. (2008). Trial sequential analysis may establish when firm evidence is reached in cumulative meta-analysis. *Journal of clinical epidemiology, 61(1)*, 64-75. https://doi.org/10.1016/j.jclinepi.2007.03.013
</p>

<a id="ref-Wetterslev2009"></a>
<p style="text-indent: -25px; margin-left: 25px;">
Wetterslev, J., Thorlund, K., Brok, J., & Gluud, C. (2009). Estimating required information size by quantifying diversity in random-effects model meta-analyses. *BMC medical research methodology, 9(1)*, 1-12. https://doi.org/10.1186/1471-2288-9-86
</p>

<a id="ref-Wetterslev2017"></a>
<p style="text-indent: -25px; margin-left: 25px;">
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. https://doi.org/10.1186/s12874-017-0315-7
</p>