# Main Functions and Arguments

We will present the main functions and their arguments in more detail.

## setup.hypothesis

To setup a hypothesis, we can either use a fitted mirt model or specify alternative parameters directly. In both cases, we use the altpars argument of the setup.hypothesis function. An example of direct specification is:

```
altpars <- list(a = rlnorm(5, sdlog = 0.4), d = rnorm(5))
hyp <- setup.hypothesis(type = "1PLvs2PL", altpars = altpars)
```

You can use the type argument to specify which type of hypothesis test you want to perform.

The following types are currently available in the package:

- Rasch against 2PL (type = “1PLvs2PL”),
- DIF in 2PL (type = “DIF2PL”),
- PCM against GPCM (type = “PCMvsGPCM”).

We have already seen the Rasch against 2PL hypothesis setup in the toy example above. The procedure for the DIF in 2PL hypothesis is analogous, yet a bit more complicated since we need to define two groups. An example is:

```
group1 <- group2 <- list(a = rlnorm(5, sdlog = 0.2),
d = rnorm(5))
group2$a[1] <- (group2$a[1])^2
group2$d[1] <- group2$d[1] + 0.5
altpars <- list(group1, group2)
hyp <- setup.hypothesis(type = "DIF2PL", altpars = altpars)
```

Note that for both hypothesis types, we do not have to provide the parameters under the null hypothesis here, because they are implicitly defined by the alternative hypothesis. The setup.hypothesis function also allows for specifying parameters under the null hypothesis via a “nullpars” argument for cases in which the parameters under the null hypothesis are not identified by the parameters under the alternative. To implement such custom hypotheses, we provide additional guidance in the “adding_hypotheses” vignette. Some templates for hypothesis objects are included in the “hypothesis_templates” vignette.

## irtpwr Function

The irtpwr function can be used to perform the power analysis. Besides an hypothesis, an alpha niveau needs to be specified. The function can:

- calculate a necessary sample size N given a desired power (using the power argument, e.g. power = .8)
- calculate the power for a specific sample size N (using the N argument, e.g. N = 600)

For example, to calculate the power for a sample size of 600 using our DIF hypothesis from above:

```
res <- irtpwr(hyp = hyp, N = 600, alpha = 0.05)
summary(res)
#>
#> Power for N = 600 (alpha = 0.05):
#>
#> Statistic Power
#> Wald 0.5411
#> LR 0.5501
#> Score 0.5481
#> Gradient 0.5523
#>
#> Method: Analytical
```

The object resulting from irtpwr can be used to gather further information about the relationship between sample size and power. For example, we can obtain the sample size necessary for reaching a power of .8.

```
summary(res, power = 0.8)
#>
#> Sample sizes for power = 0.8 (alpha = 0.05):
#>
#> Statistic N
#> Wald 1061
#> LR 1039
#> Score 1044
#> Gradient 1034
#>
#> Method: Analytical
```

We can also obtain the power for a different sample size than originally specified in our execution of the irtpwr function.

```
summary(res, N = 700)
#>
#> Power for N = 700 (alpha = 0.05):
#>
#> Statistic Power
#> Wald 0.6109
#> LR 0.6203
#> Score 0.6182
#> Gradient 0.6227
#>
#> Method: Analytical
```

The irtpwr function builds on one of two available methods that are described in our paper in more detail (Zimmer et al. (2022), https://doi.org/10.1007/s11336-022-09883-5):

- an analytical approach (method = “analytical”, this is the default option)
- a sampling-based approach (method = “sampling”)

To use the sampling based approach, we can execute:

```
res <- irtpwr(hyp = hyp, N = 600, alpha = 0.05, method = "sampling")
summary(res)
#>
#> Power for N = 600 (alpha = 0.05):
#>
#> Statistic Power
#> Wald 0.5877
#> LR 0.5975
#> Score 0.5956
#> Gradient 0.6000
#>
#> Method: Sampling-Based
```

The sampling-based approach offers two parameters that can be increased from their default values to obtain a more exact result. These are the sample size of the sampling-based approach (sampling.npers) and the sample size for the approximation of the Fisher expected matrix (approx.npers). These may be tweaked upwards if the result from repeated executions of the irtpwr function is not stable.

Since the analytical approach can be too time-intensive for larger numbers of items, we might want to know beforehand how long it will take approximately. We do so using the calc.time function.

In our example hypothesis, we used 5 items. To estimate the computation time for 7 items we can use:

Note that the estimated time can sometimes deviate from the actual time. As a result from our test runs, we suggest to expect an increase of 80% as a worst case scenario.