---
title: "anomo"
author: "Zuchao Shen"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{anomo}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
This package offers statistical power calculation for designs detecting 
equivalence of two-group means. It also performs optimal sample allocation and
provides the Monte Carlo confidence interval (MCCI) method to test the 
significance of equivalence. 

# 1. The mcci Function 
## (1) Key Arguments in the mcci Function

To compute the MCCI for difference or equivalence tests, the minimum argument is
the estimated effect and its standard errors. The function can take up to 
two sets of effects and their standard errors. For each set, it could include
components of a compound effect (i.e., a mediation effect). 

When only one set of argument is specified, 
the effect itself is estimated difference.

- d1: The estimated effect in a study.
- se1: The standard error(s) of d1.

When two sets of effects/means are specified, 
they could be like the following.

- d1: The estimated mean (or effect(s)) for group 1 (study 1).
- se1: The standard error(s) of d1.
- d2: The estimated mean (or effect(s)) for group 2 (study 2).
- se2: The standard error(s) of d2.

## (2) Plots Provided by the Function
The function also provide a plot of the MCCI by default. 
Arguments are available to adjust the appearance of the plot. 
See the function documentation for details.

# 2. The power.eq.2group Function
This function performs power analysis for equivalence test of two-group means. 
It can calculate statistical power, required sample size, and 
the minimum detectable difference between equivalence bounds and
the group-mean difference depending on which one and 
only one of parameters is unspecified in the function.

- power: statistical power.
- n: sample size.
- eq.dis: The minimum distance between the equivalence bounds and the 
difference in means (effect(s)) .

# 3. Examples

## (1) MCCI Example

```{r fig.width = 7, fig.height = 3.5}
 library(anomo)
myci <- mcci(d1 = .1, se1 = .1, d2 = .3, se2 = .1)
# Note. Effect difference (the black square representing d2 - d1), 90% MCCI 
# (the thick horizontal line) for the test of equivalence, and 95% MCCI 
# (the thin horizontal line) for the test of moderation 
# (or difference in effects).

```


```{r}
# Adjust the plot
myci <- mcci(d1 = .1, se1 = .1, d2 = .4, se2 = .1,
             eq.bd = c(-0.2, 0.2), xlim = c(-.2, .7))
```


-MCCI for the difference and equivalence in mediation effects
(product of the y~m and m~x paths) in two studies

```{r fig.width = 7, fig.height = 3.5}
MyCI.Mediation <- mcci(d1 = c(.60, .40), 
             se1 = c(.019, .025),
             d2 = c(.60, .80),
             se2 = c(.016, .023))
```

## (2) Power Analysis Example

### Conventional Power Analysis
```{r conventional.power.analysis}
 # 1. Conventional Power Analyses from Difference Perspectives
 # Calculate the required sample size to achieve certain level of power
 mysample <- power.eq.2group(d = .1, eq.dis = 0.1,  p =.5,
                             r12 = .5, q = 1, power = .8)
 mysample$out
 # Calculate power provided by a sample size allocation
 mypower <- power.eq.2group(d = 0.1, eq.dis = 0.1, n = 1238, p =.5,
                            r12 = .5, q = 1)
 mypower$out
 # Calculate minimum detectable distance a given sample size allocation can achieve
 myeq.dis <- power.eq.2group(d = .1, n = 1238, p =.5,
                            r12 = .5, q = 1, power = .8)
 myeq.dis$out
```

### Power Analysis with Costs

```{r power.analysis.with.costs}
 # 2. Power Analyses Using Optimal Sample Allocation
 # Optimal sample allocation identification
 od <- od.eq.2group(r12 = 0.5, c1 = 1, c1t = 10)
 # Required budget and sample size at the optimal allocation
 budget <- power.eq.2group(expr = od, d = 0.1, eq.dis = 0.1,
                            q = 1, power = .8)  
 # Required budget and sample size by an balanced design with p = .50
 budget.balanced <- power.eq.2group(expr = od, d = 0.1, eq.dis = 0.1,
                                    q = 1, power = .8,
                                    constraint = list(p = .50))
 # 27% more budget required from the balanced design with p = 0.50.
 (budget.balanced$out$m-budget$out$m)/budget$out$m *100
```

### Power Curve Under the Same Budget: Statistical Power is Maximized at the Optimal Allocation

```{r power.curve} 
pwr <- NULL
p.range <- seq(0.01, 0.99, 0.01)
for(p in p.range){
  pwr <- c(pwr, power.eq.2group(expr = od, constraint = list(p = p),
                                m = budget$out$m, d = 0.1, eq.dis = 0.1,
                                q = 1, verbose = FALSE)$out$power)
}
plot(p.range*100,
     pwr*100,
     type = "l", lty = 1,
     xlim = c(0, 100), ylim = c(0, 100),
     xlab = "Proportion of Units in Treated (%)", ylab = "Power (%)",
     main = "", col = "black")
abline(v=od$out$p*100, lty = 2, col = "black")
```