polyICT: 'polyICT' class generator

In ICTatRTI/PersonAlyticsPower: Power Analysis and Simulation for PersonAlytics

polyICT class generator

Description

polyICT class generator

polyICT class generator

Usage

polyICT$new()

Details

The polyICT class generator specifies the inputs needed to simulate data from a polynomial growth model. Once a polyICT object is created, you can called its methods and examine or update its fields.

Methods are functions that come packaged within your polyICT object and include $print() for printing the inputs, $update() for changing the inputs, $designCheck() for visualizing the design, and $makeData for simulating a single data set. See the section titled Methods.

Fields are all the data stored within a polyICT object, some of which are provided by the user when initializing a polyICT object, and others which are derived from these inputs and cannot be changed by the user directly. These are detailed in the section titled Fields. Fields can be accessed using the $ operator. For example, if your polyICT object is called myPolyICT, use myPolyICT$inputMat.

Methods

new

Used to initialize a polyICT object as illustrated in the Examples below. The following parameters can be passed to $new():

groups Named numeric vector. The default is c(group1=10, group2=10). The values are the number of participants per group and the names are the group names.

phases Named list. The default is created using the helper function makePhase. Each item in the list replicates the phase name as many times as there are time points in that phase. Actual time points are derived during initialization and stored in the field designMat.

propErrVar Named numeric vector of length 3. The default is c(randFx=.5, res=.25, mserr=.25). The names must be randFx, the proportion of the total variance due to random effects; res, the proportion of the total variance due to residual autocorrelation; and mserr, the proportion of total variance due to measurement error. The three values must be proportions and must sum to 1.

randFxOrder Numeric vector. The default is 1. This is used to specify the order of the polynomial growth model as follows: randFxOrder=0 is an intercept only model, randFxOrder=1 adds random slopes, randFxOrder=2 is a quadratic growth model, randFxOrder=3 is a cubic growth model, etc.

randFxCor Numeric. The correlation(s) between all of the random effects. This can be edited later and made group and/or phase specific. See the Examples.

randFxVar Numeric vector. The default is c(1, 1). This parameter is used to specify the variances of the random effects. The number of variances should equal randFxOrder + 1. The random effects variances are created as Var[o] = propErrVar$randFx * (randFxVar[o]/sum(randFxVar)) where o=0:randFxOredr. Hence randFxVar specifies the ratios of the variance that is partitioned among the random effects and rescaled by propErrVar$randFx. See makeData in the Methods section for more details.

error An error object for the residual autocorrelation. The default is armaErr$new(list(ar=c(.5), ma=c(0))), a first order AR process with phi_1=.5. See armaErr. See makeData in the Methods section for more details.

merror An error object for the measurement error. The default is armaErr$new(list(), a white noise process. See armaErr. Also see makeData in the Methods section for more details.

ymean Numeric. The default is 100. The mean of the final data. If either yMin or yMax are not NULL, ymean is ignored.

ySD Numeric. The default is 15. The standard deviation of the final data. If both yMin and yMax are not NULL, ySD is ignored.

yMin Numeric. The default is NULL in which case yMin is ignored. The minimum value for the final data.

yMax Numeric. The default is NULL in which case yMax is ignored. The maximum value for the final data.

print

See designICT.

designCheck

See designICT.

update

A method to update editable field in a polyICT object. Fields that can be updated are those listed in new. New values are passed by name using, for example, $update(groups=c(group1=25, group2=25), randFxOrder=2). The are no defaults and any number of fields can be updated at once.

makeData

A method to simulate one data set from the settings in a given polyICT object. This method is not intended to be used directly by the user, who should instead use ICTpower to automate a power analysis for one ICT design, or ICTpowerSim for conducting a full power analysis simulation study. The parameters are

seed Numeric. The default is 123. A random seed for reproducibility. If multiple calls are made to makeData, the seed should change for each call as is done automatically by ICTpower.

Super class

PersonAlyticsPower::designICT -> polyICT

Public fields

inputMat

A data.frame containing the inputs needed for data simulation by phase and by group. Columns include Phase, Group, nObs (the number of observations in a given phase), n (the number of participants in a given group), the means and variances for each random effect (see randFxOrder under new in the Methods section), and the variance partioning (see propErrVar under new in the Methods section). Instructions for editing this field are given in the Examples.

The Mean columns are standardized effect sizes on the scale of Cohen's d. For more detailed information and illustrations, see the Example section.

randFxVar

See randFxVar in the new method. Phase and/or group specific variances can be specified by editing inputMat after initializing a polyICT object.

randFxCor

A default correlation between the random effects. This can be edited later as shown in the examples.

propErrVar

See propErrVar in the new Method. See also inputMat and the Examples for making these inputs phase and/or group specific.

error

See error in the new Method. See also armaErr.

merror

See merror in the new Method.

yMean

See yMean in the new Method.

ySD

See ySD in the new Method.

yMin

See yMin in the new Method.

yMax

See yMax in the new Method.

n

The total sample size.

nObs

The total number of observations (i.e., time points).

groups

See groups in the new Method.

phases

See phases in the new Method.

designMat

The design matrix with phases and timepoints.

meanNames

The columns of InputMat corresponding to the effect sizes/random effect means.

varNames

The columns of InputMat corresponding to the random effect variances.

phaseNames

The names of the phases, taken from phases.

groupNames

The names of the groups, taken from groups.

randFxFam

A gamlss.family distribution for non-normal random effects. Not implemented.

randFxFamParms

The parameters for the gamlss.family distribution specified in randFxFam. Not implemented.

Active bindings

inputMat

A data.frame containing the inputs needed for data simulation by phase and by group. Columns include Phase, Group, nObs (the number of observations in a given phase), n (the number of participants in a given group), the means and variances for each random effect (see randFxOrder under new in the Methods section), and the variance partioning (see propErrVar under new in the Methods section). Instructions for editing this field are given in the Examples.

The Mean columns are standardized effect sizes on the scale of Cohen's d. For more detailed information and illustrations, see the Example section.

randFxVar

See randFxVar in the new method. Phase and/or group specific variances can be specified by editing inputMat after initializing a polyICT object.

randFxCor

A default correlation between the random effects. This can be edited later as shown in the examples.

propErrVar

See propErrVar in the new Method. See also inputMat and the Examples for making these inputs phase and/or group specific.

error

See error in the new Method. See also armaErr.

merror

See merror in the new Method.

yMean

See yMean in the new Method.

ySD

See ySD in the new Method.

yMin

See yMin in the new Method.

yMax

See yMax in the new Method.

n

The total sample size.

nObs

The total number of observations (i.e., time points).

groups

See groups in the new Method.

phases

See phases in the new Method.

designMat

The design matrix with phases and timepoints.

meanNames

The columns of InputMat corresponding to the effect sizes/random effect means.

varNames

The columns of InputMat corresponding to the random effect variances.

phaseNames

The names of the phases, taken from phases.

groupNames

The names of the groups, taken from groups.

randFxFam

A gamlss.family distribution for non-normal random effects. Not implemented.

randFxFamParms

The parameters for the gamlss.family distribution specified in randFxFam. Not implemented.

Methods

Public methods

• polyICT$new()

• polyICT$print()

• polyICT$update()

• polyICT$makeData()

• polyICT$clone()

Inherited methods

• PersonAlyticsPower::designICT$designCheck()

---

Method new()

Usage

polyICT$new(
  groups = c(group1 = 10, group2 = 10),
  phases = makePhase(),
  propErrVar = c(randFx = 0.5, res = 0.25, mserr = 0.25),
  randFxOrder = 1,
  randFxCor = 0.2,
  randFxVar = c(1, 1),
  error = armaErr$new(),
  merror = armaErr$new(list()),
  ySD = 1,
  yMean = 0,
  yMin = NULL,
  yMax = NULL,
  yCut = NULL,
  randFxFam = qNO,
  randFxFamParms = list(mu = 0.5, sigma = 1)
)

---

Method print()

Usage

polyICT$print(...)

---

Method update()

Usage

polyICT$update(...)

---

Method makeData()

Usage

polyICT$makeData(seed = 123, y0atyMean = TRUE, yMean = 0)

---

Method clone()

The objects of this class are cloneable with this method.

Usage

polyICT$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Author(s)

Stephen Tueller [e-mail]

Examples

# Set up a new polyICT object using the default parameter settings

myPolyICT <- polyICT$new(
  groups            = c(group1=10, group2=10)          ,
  phases            = makePhase()                      ,
  propErrVar        = c(randFx=.5, res=.25, mserr=.25) ,
  randFxOrder       = 1                                ,
  randFxCor         = 0.2                              ,
  randFxVar         = c(1, 1)                          ,
  error             = armaErr$new()                    ,
  merror            = armaErr$new(list())              ,
  ySD               = 15                               ,
  yMean             = 100                              ,
  )

# print the object

myPolyICT
# equivalent to:
#print(myPolyICT)
#myPolyICT$print()

# fields can be accessed directly using $
myPolyICT$inputMat
myPolyICT$designMat

# edit the means in inputMat so that
#
# 1. group1 is left with no change in all three phases
# 2. group2 has no change at phase1 (i.e., baseline), phase2 has a phase
#    jump to d=.3 with no within phase change, and phase3 starts where it
#    left off at d=.3 and decreases by d=-.6 through the remained of the
#    phase.
#
# Note that editing inputMat may be easier using
#edit(myPolyICT)
# but this is more diffucult to replicate.
myPolyICT$inputMat[myPolyICT$inputMat$Phase=='phase2' &
  myPolyICT$inputMat$Group=='group2', 'Mean0'] <- .3
myPolyICT$inputMat[myPolyICT$inputMat$Phase=='phase3' &
  myPolyICT$inputMat$Group=='group2', 'Mean0'] <- .6
myPolyICT$inputMat[myPolyICT$inputMat$Phase=='phase3' &
  myPolyICT$inputMat$Group=='group2', 'Mean1'] <- -.06
myPolyICT$inputMat

# now do a large sample (n=5,000/group) check of the design using $designCheck.
# Notice that in group 2, there is a jump of about .3*15=4.5 between phases
# one and two, and that within phase 3 there is -.6*15=-9 point reduction. This
# is not run when calling example(polyICT) due to it taking several seconds to
# simulate the large sample data.


## Not run: 

myPolyICT$designCheck()

# for comparison, see what can happen under finite samples (n=10/group).
# Notice that there are substantial changes in group1 even though none are
# specified, and that the changes in group2 can be different from what was
# specified. This illustrates possible. finite sample behaviors.

myPolyICT$designCheck(seed=1, npg=10, ylim=c(75,125))
myPolyICT$designCheck(seed=2, npg=10, ylim=c(75,125))
myPolyICT$designCheck(seed=3, npg=10, ylim=c(75,125))


## End(Not run)

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