ICTpower: ICTpower - get simulated power for an ICT design using...

In ICTatRTI/PersonAlyticsPower: Power Analysis and Simulation for PersonAlytics

ICTpower - get simulated power for an ICT design using parametric or non-parametric bootstrap.

Description

ICTpower - get simulated power for an ICT design using parametric or non-parametric bootstrap.

Usage

ICTpower(
  outFile = NULL,
  design = NULL,
  interactions = NULL,
  B = 100,
  dataFile = NULL,
  sampleSizes = NULL,
  alpha = 0.05,
  seed = 123,
  cores = parallel::detectCores() - 1,
  savePowerReport = TRUE,
  standardize = list(dv = FALSE, ivs = FALSE, byids = FALSE),
  userFormula = list(fixed = NULL, random = NULL, formula = NULL),
  prompt = TRUE,
  y0atyMean = TRUE,
  ...
)

Arguments

outFile	The file name for saving power analysis results. It may be a full path. The simulated data are to be saved by including the file extension in a list. For example, outFile=c('n10_medSlopeEffect', 'csv') or outFile=c('condition2', 'Rdata'). Only 'csv' and 'RData' are supported.
design	An designICT object such as polyICT. This must be provided for a parametric bootstrap estimate of power.
interactions	A list of pairs of variables for which two-way interactions should be estimated. Variables that can be included in this list are Time, phase, and group. The default is NULL in which all pairs are included if they appear in the data, equivalent to interactions = list(c("Time", "phase"), c("Time", "group"), c("group", "phase")).
B	The number of simulated dataset (or parametric bootstrap replications).
dataFile	Character. A file name for exntant data. Use this option to do a non-parametric bootstrap (e.g., for finite sample power). If dataFile is provide, design will be ignored. The dataFile must be a *.csv file with the variables 'id' and 'Time', optionally 'phase' and/or 'group', and dependent variables labeled 'y'. Alternatively, dataFile may be a *.Rdata file named 'Data' with the same columns as described for the *.csv file.
sampleSizes	Numeric vector of the same length as the number of groups in the data. The group specific sample sizes to be drawn B times from the dataFile data.
alpha	Numeric. Default is .05. The Type I error rate for computing empirical power (i.e., the proportion of p-values across B data sets that are less than or equal to alpha).
seed	A random seed for replicating the power analysis.
cores	The number of cores used in parralelized simulation (for a parametric bootstrap) and for fitting models to the data for both bootstrap types (see PersonAlytic). The default is to use one fewer cores than are detected on the computer. Do not exceed the maximum available cores or unexpected results may occur and R may crash.
savePowerReport	Should the power report be saved using the outFile name? If TRUE, a 'txt' file is saved in the working directory. This option is set to FALSE in the function ICTpowerSim which instead saves the reports from several conditions in a 'csv' file.
standardize	Named list of length 3. Default is list(dv = TRUE, ivs = FALSE, byids = TRUE). See PersonAlytic or Palytic.
userFormula	List of equations, see PersonAlytic. Default is NULL. Only userFormula$fixed is currently supported.
prompt	Logical. Default is TRUE. If TRUE, a check for whether outFile already exists will be done and if so, the user will be prompted whether they want to overwrite outFile. The ICTpowerSim function turns this off so the user does not have to monitor a series of simulations.
y0atyMean	Logical. Default is TRUE. If TRUE, after data are standardized, they are re-centered such that the mean of the outcome at the baseline phase is yMean.
...	Further arguments to be passed to PersonAlytic for analysis. All options in PersonAlytic can be passed except for output, data, ids, dvs, time, and phase as these are taken from the design (for parametric bootstrapping) or from the dataFile (for non-parametric bootstrapping).

Author(s)

Stephen Tueller [e-mail]

Examples

## Not run: 

example(polyICT)
myPolyICT$inputMat

# parametric examples with safe cloning using deep=TRUE
myPolyICT2 <- myPolyICT$clone(deep=TRUE)
myPolyICT2$inputMat$n <- c(20,20)
testICTpower20 <- ICTpower(c('testICTpower_n20_20', 'csv'),
  myPolyICT2, B=3, seed = 25, prompt=FALSE)

myPolyICT3 <- myPolyICT$clone(deep=TRUE)
myPolyICT3$inputMat$nObs <- c(15, 60, 20)
testICTpower20t100 <- ICTpower(c('testICTpower_nObs15_60_20', 'csv'),
  myPolyICT3, B=3, seed = 26, prompt = FALSE)

# non-parametric bootstrap examples

# create a population with 500 participants per group
myPolyICTnonPar <- myPolyICT$clone(deep=TRUE)
myPolyICTnonPar$inputMat$n <- c(500, 500)
Data <- myPolyICTnonPar$makeData()
save(Data, file = "Data.RData")

# non parametric bootstrap samlpes of 25 participants each group
ICTpower(outFile     = c("npbsTest", "csv") ,
         B           = 3                    ,
         dataFile    = "Data.RData"         ,
         sampleSizes = c(25,25)             ,
         prompt      = FALSE                )

# with a finite power correction passing `fpc`
ICTpower(outFile     = c("npbsFPCtest", "csv") ,
         B           = 3                       ,
         dataFile    = "Data.RData"            ,
         sampleSizes = c(25,25)                ,
         fpc         = length(table(Data$id))  ,
         prompt      = FALSE                   )

# piecewise growth model example
ICTpower(outFile     = c("piecewise", "csv"),
         B           = 3                    ,
         dataFile    = "Data.RData"         ,
         sampleSizes = c(25,25)             ,
         alignPhase  = 'piecewise'          ,
         prompt      = FALSE                )

# Timing run for B=1000
start_time <- Sys.time()
myPolyICT2 <- myPolyICT$clone(deep=TRUE)
myPolyICT2$update(groups=c(group1=20, group2=20))
testICTpower20 <- ICTpower(c('testICTpower20_B1000', 'csv'),
  myPolyICT2, B=1000, seed = 25, prompt=FALSE)
end_time <- Sys.time()
end_time - start_time

# clean up - only run if you want to deletet all txt, csv, and RData files in
# the current working directory
#toDelete <- dir(getwd())
#toDelete <- toDelete[grepl(".txt|.csv|.RData", toDelete)]
#file.remove( toDelete )

## End(Not run)

ICTatRTI/PersonAlyticsPower documentation built on Dec. 13, 2024, 11:08 p.m.