Type: Package
Title: Estimate Power and Required Sample Size in QCA
Version: 0.1.0
Imports: ggplot2, ggforce, devtools, stats
Depends: R (≥ 2.10)
Description: Researchers working with Qualitative Comparative Analysis (QCA) can use the package to estimate power of a sufficient term using permutation tests. A term can be anything: A condition, conjunction or disjunction of any combination of these. The package further allows users to plot the estimation results and to estimate the number of cases required to achieve a certain level of power, given a prespecified null and alternative hypothesis. Reference for the article introducing power estimation for QCA is: Rohlfing, Ingo (2018) <doi:10.1017/pan.2017.30> (ungated version: <doi:10.17605/OSF.IO/PC4DF>).
License: GPL-3
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.0.2
Suggests: knitr, rmarkdown
VignetteBuilder: knitr
URL: https://github.com/ingorohlfing/qcapower
BugReports: https://github.com/ingorohlfing/qcapower
NeedsCompilation: no
Packaged: 2020-02-24 16:34:11 UTC; Ingo R
Author: Ingo Rohlfing [aut, cre], Holger Doering [aut], Ayjeren Rozyjumayeva [aut]
Maintainer: Ingo Rohlfing <i.rohlfing@uni-koeln.de>
Repository: CRAN
Date/Publication: 2020-03-02 13:40:02 UTC

qcapower returns a power estimate with regard to the consistency of a term, given information about the required parameters

Description

qcapower allows you to estimate power for a term. Probability is the probability of rejecting the null hypothesis that no set relation is in plaace when it is in place, in fact. A term can be a single condition, a conjunction, or a disjunction of any combination of the two.

Usage

qcapower(
  cases,
  null_hypo,
  alt_hypo,
  sims = 1000,
  perms = 10000,
  alpha = 0.05,
  cons_threshold = 0.01,
  set_seed = 135
)

Arguments

cases

Number of cases. In fuzzy-set QCA, equal to total number of cases in the analysis

null_hypo

Null hypothesis (H0). Consistency value separating consistent from inconsistent terms. It is the highest possible consistency value that would let you conclude that no set relation is given.

alt_hypo

Alternative hypothesis (H1). Expected, actual consistency value of term.

sims

Number of simulations for calculating power

perms

Number of permutations of hypothetical dataset per simulation run

alpha

Level of alpha at which statistical significance of H0 is tested

cons_threshold

Degree of tolerance in generating hypothetical data with consistency equaling alt_hypo (see vignette)

set_seed

Parameter for achieving reproducibility of estimate

Value

A dataframe with rows equaling the number of sims. power is the power estimate and is identical for each rows. powercum is the running power estimate up to this row. quant is the 5%-quantile of the permuted distributions. See the vignette for more information.

See Also

qp_quant_plot and qp_run_plot

Examples

power_data <- qcapower(cases = 20, null_hypo = 0.8, alt_hypo = 0.95, sims = 10, perms = 1000)
head(power_data)

Calculte the number of cases for a particular case target based on simulated data

Description

qp_cases calculates the number of cases needed for a particular power level. It is based on the presimulated data using qcapower. See the vignette for more details.

Usage

qp_cases(power_target, null_hypo, alt_hypo)

Arguments

power_target

Desired level of power

null_hypo

Null hypothesis (H0). Consistency value separating consistent from inconsistent terms.

alt_hypo

Alternative hypothesis (H1). Expected, actual consistency value of term.

Value

An integer showing how many cases are needed to achieve the target level of power.

See Also

qp_cases_brute

Examples

qp_cases(0.1, null_hypo = 0.8, alt_hypo = 1)

Calculate the number of cases for a particular case target with iterative simulations (brute force)

Description

qp_cases_brute calculates the number of cases needed for a particular power level. The function starts with the number of cases given by start_value and iteratively simulates power and adjusts the number of cases until the power_target is met or the max_value has been reached. Running the function can take a lot of time. Use qp_cases to

Usage

qp_cases_brute(
  power_target,
  start_value = 2,
  max_value = 100,
  progress = TRUE,
  ...
)

Arguments

power_target

Power level target

start_value

Default number of cases for initial search

max_value

Default maximum number of cases for search

progress

Show progress of calculation (default TRUE)

...

qcapower parameters – see qcapower

Value

An integer showing how many cases are needed to achieve the target level of power.

See Also

qp_cases_brute

Examples

## Not run: 
qp_cases_brute(power_target = 0.9, null_hypo = 0.80, alt_hypo = 1)

qp_cases_brute(power_target = 0.9, null_hypo = 0.80, alt_hypo = 1, start_value = 20,
               max_value = 50, perms = 500)

## End(Not run)

Sina plot of 5 distributions

Description

Depending on the number of cases, the permuted distributions of consistency values can differ narrowly or widely in terms of their location on the spectrum and their shape.

Usage

qp_quant_plot(power_est, title = FALSE)

Arguments

power_est

Dataframe containing simulation results (see qcapower)

title

Option for adding title to plot (default FALSE)

Details

Creates a sina plot with ggforce

Value

A sina plot using the cases to visualize the density distribution ('gg' object).

Examples

sim_data <- qp_sina_data
qp_quant_plot(sim_data)

Plot of power estimate against the number of simulations

Description

qp_run_plot allows you to plot the running power estimate to determine whether sims is sufficiently large to derive a reliable estimate

Usage

qp_run_plot(power_est, title = FALSE)

Arguments

power_est

Dataframe containing the simulation results (see qcapower)

title

Option for adding title to plot (default FALSE)

Details

Creates a plot with ggplot2

Value

A line plot ('gg' object).

Examples

power_data <- qcapower(cases = 20, null_hypo = 0.8, alt_hypo = 0.95, sims = 10, perms = 1000)
qp_run_plot(power_data)

# Using data with 10000 estimates
data(qp_sina_data)
qp_run_plot(qp_sina_data)

Data simulated power estimates

Description

A dataset containing power simulations for different number of cases and different values for null- and alternative hypothesis

Usage

qp_sim_power

Format

A dataframe with simulation parameters and calculated power

Details

cases

number of cases

null_hypo

null hypothesis (H0)

alt_hypo

alternative hypothesis

sims

number of simulations

perms

number of permutations

perms

calculate power

Data simulated power estimates for plotting of 5%-quantiles

Description

A dataset containing the estimated 5%-quantiles from a power simulation with 1000 simulations each with 10000 permutations. The value for the alternative hypothesis was set to 1.

Usage

qp_sina_data

Format

A dataframe with 1000 rows and 6 variables:

Details

power

power estimate over 1000 simulations

powercum

running power estimate for ith simulation

null_hypo

null hypothesis (H0), set to 0.8 (irrelevant here)

alt_hypo

alternative hypothesis (H1), set to 1

cases

number of cases, set to 10

quant

estimated 5%-quantiles per simulations