Calculate the point of stability for a two-way interaction estimate

Usage

run_pos_power_search(
  r.x1.y,
  r.x2.y,
  r.x1x2.y = NULL,
  r.x1.x2,
  rel.x1,
  rel.x2,
  rel.y = 1,
  single.N = NULL,
  start.power = 0.8,
  step = NULL,
  n.datasets = 1000,
  lower.bound = NULL,
  upper.bound = NULL,
  cos.width = 0.5,
  pos.percent = 0.8,
  n.cores = 1
)

Arguments

r.x1.y: Pearson's correlation between x1 and y. Must be between -1 and 1. Has no default value.
r.x2.y: Pearson's correlation between x2 and y. Must be between -1 and 1. Assumed to be the 'moderator' in some functions. Has no default value.
r.x1x2.y: Pearson's correlation between the interaction term x1x2 (x1 * x2) and y. Must be between -1 and 1. If NULL or unspecified, it is automatically assigned as the average of the main effects divided by 2, considering reliability. The default value is NULL.
r.x1.x2: Pearson's correlation between x1 and x2. Must be between -1 and 1. Has no default value.
rel.x1: Reliability of x1 (e.g. test-retest reliability, ICC, Cronbach's alpha). Default is 1 (perfect reliability). Must be greater than 0 and less than or equal to 1.
rel.x2: Reliability of x2 (e.g. test-retest reliability, ICC, Cronbach's alpha). Default is 1 (perfect reliability). Must be greater than 0 and less than or equal to 1.
rel.y: Reliability of xy (e.g. test-retest reliability, ICC, Cronbach's alpha). Default is 1 (perfect reliability). Must be greater than 0 and less than or equal to 1.
single.N: Numeric or NULL. A specific sample size at which the stability statistics (POS, COS) are computed. A numeric value overrides the search for a POS. Must be a whole number greater than 0 or NULL. Default is NULL.
start.power: Numeric or NULL. Determines the starting sample size of the search by locating the sample size with power equal to start.power. If it is non-null, it must be greater than 0 and less than 1. Note that a non-null start.power overrides user inputs for the parameters lower.bound and upper.bound so both are NULL. The default is 0.8.
step: Numeric or NULL. Determines the rounding (degree of precision) in the estimate of the POS. When set to NULL, dynamic adjustments are made with 1/100th the of the interval between the upper.bound and lower.bound on each iteration of the search algorithm. If it is non-null, it must be a whole natural number. Default is NULL.
n.datasets: Numeric. Number of simulations conducted at each sample size identified by the search process. Larger values result in greater computational demands. Default is 10000. Must be greater than 1.
lower.bound: Numeric or NULL. The lower bound for the search. It is automatically assigned when set to NULL The user can manually input one. There is an automatic override to NULL if start.power is non-null. The default is NULL.
upper.bound: Numeric or NULL. The upper bound for the search. If it is null, an upper bound is determined automatically; there is a ceiling of 1e7. Default is NULL.
cos.width: Numeric. The width of the corridor of stability COS within which we require some number of estimates to fall to identify the POS. Must be greater than 0. Values above 1 are unlikely to be informative. Default is 0.5.
pos.percent: Numeric. The minimum proportion of simulated estimates we require to fall inside the COS to consider the sample size to produce stable estimates. Default is 0.8.
n.cores: Numeric. Number of cores to be used in parallel processing. Default is 1.

Value

A data frame containing the variables 'rel.x1', 'rel.x2', 'rel.x1x2', 'rel.y', 'r.x1x2.y', 'r.x1.y', 'r.x2.y', 'obs.r.x1x2.y', 'COS_pos.percents', 'COS_interval', 'POS_samplesize', and 'POS_power' OR a data frame containing the variables 'single.N', 'rel.x1', 'rel.x2', 'rel.x1x2', 'rel.y', 'r.x1x2.y', 'r.x1.y', 'r.x2.y', 'obs.r.x1x2.y', 'COS_pos.percents', 'within_COS_interval', 'POS_determined_COS', 'within_POS_determined_COS', 'POS_determined_COS.percent', sign_error_rate', and 'power' If the user inputs single.N as NULL, the first dataframe is returned with the search results for the POS. If the user inputs single.N as a numeric whole number greater than 3, the second dataframe is returned with stability information at that specific sample size.

    COS_pos.percents: A string representing the COS width and target POS percentage.

    within_COS_interval: The proportion of estimates within the inputted COS at the sample size single.N.

    POS_determined_COS: The COS necessary to achieve the inputted pos.percent at the sample size single.N. There is a ceiling of 100 times the magnitude of the estimate.

    within_POS_determined_COS: The proportion of estimates within the POS_determined_COS at the sample size single.N.

    POS_determined_COS.percent: The percent deviation from the expected value defining POS_determined_COS.

    sign_error_rate: The number of estimates signed incorrectly at the sample size single.N.

    power: The statistical power, calculated analytically, at the sample size single.N.

    r.x1x2.y_to_be_stable_at_single.N: The minimum interaction effect required for stability at the sample size single.N, determined via binary search.

    power_to_be_stable: The statistical power associated with the stable_effect_size at sample size single.N.

Examples

run_pos_power_search(r.x1.y = 0.2, r.x2.y = 0.2, r.x1x2.y = 0.15, r.x1.x2 = 0.1,
rel.x1 = 0.8, rel.x2 = 0.8,start.power = 0.8, step = NULL, n.datasets = 1000,
lower.bound = NULL, upper.bound = 500, cos.width = 0.5, pos.percent = 0.8)
#> The sample size at the start.power of 0.8 is 515. Re-running the search with lower.bound set to 258 and upper bound set to 515. 
#>   rel.x1 rel.x2  rel.x1x2 rel.y r.x1x2.y r.x1.y r.x2.y r.x1.x2 obs.r.x1x2.y
#> 1    0.8    0.8 0.6435644     1     0.15    0.2    0.2     0.1    0.1203337
#>   COS_pos.percents     COS_interval POS_samplesize POS_power
#> 1         (50, 80) [0.0602, 0.1805]            459 0.7529432