---
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 required arguments are the estimate(s) and corresponding standard error(s). The function can take up to 
five sets of estimates and their standard errors. It could include
components of one or two mediation effects if mediation is TRUE. 

- d: The estimate(s).
- se: The standard error(s) of d.

When two or more sets of parameters are specified (and mediation is FALSE), the function computes the MCCIs for the difference across these estimates. When mediation is TRUE,
the function computes the MCCIs for the estimated mediation effects (in one study) or the difference across these mediation effects (in two studies/groups).

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

# 2. The od Functions
These functions identify optimal sample allocation for different types of experiments where the maximum statistical is achieved under a fixed budget. 


# 3. The plot.power.eq Function
This function plots the statistical power curves under a fixed budget to illustrate the optimal design identification.

# 4. The power Functions
These functions perform power analyses for equivalence test in different types of designs. 
They can calculate statistical power, required sample size, and 
the minimum detectable difference between equivalence bounds and
the estimate depending on which one and 
only one of parameters is unspecified in the function.

For example, the power.1.eq function for randomized controlled trials
detecting equivalence has the following arguments.

- power: statistical power.
- n: sample size.
- d: estimate (e.g., difference in group means).
- eq.dis: The minimum distance between the equivalence bounds and the 
difference in means.

# 5. Examples

## (1) MCCI Example

```{r fig.width = 7, fig.height = 3.5}
 library(anomo)
myci <- mcci(d = c(.1, .15), se = c(.01, .01))
# Note. Effect difference (the black square representing d1 - d2), 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(d = c(.1, .15), se = c(.01, .01),
             eq.bd = c(-0.2, 0.2), xlim = c(-.2, .7))
```


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

```{r fig.width = 7, fig.height = 3.5}
MyCI.Mediation <- mcci(d = c(.60, .40, .60, .80), 
             se = c(.019, .025, .016, .023), mediation = TRUE)
#Note. The order of d is a1, b1, a2, and b2 (e.g., treatment-mediator
#   and mediator-outcome path in group/study 1 and 2, respectively). 
#   se is in the same order for the standard errors.
```

## (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.1.eq(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.1.eq(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.1.eq(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.1.eq(r12 = 0.5, c1 = 1, c1t = 10)
 # Required budget and sample size at the optimal allocation
 budget <- power.1.eq(expr = od, d = 0.1, eq.dis = 0.1, 
                         power = .8)  
 # Required budget and sample size by an balanced design with p = .50
 budget.balanced <- power.1.eq(expr = od, d = 0.1, eq.dis = 0.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} 
plot.power.eq(expr = od, d = 0.1, eq.dis = 0.1) 
```