SeqSGPV: Sequential Monitoring of Second Generation P-Value (SeqSGPV)

In chipmanj/SeqSGPV: Sequential Monitoring of Scientific Regions Using the Second Generation P-Value

Sequential Monitoring of Second Generation P-Value (SeqSGPV)

Description

The Second Generation p-Value (SGPV) incorporates pre-specified clinical context to monitor studies until either ruling out trivial or impactful effects. Operating characteristics may be determined via simulation. This function allows the user to use either their own generated data or to generate their own data from any of R's random data generators.

Data are either provided from one's own simulations or via monte-carlo simulations of data, using dataGeneration, dataGenArgs, effectGeneration, and effectGenArgs. When one's own data are provided, it must be in matrix format with at least the columns: 'theta', 'est', 'lo' (lower bound), and 'up' (upper bound). Otherwise, data are generated until the final maxAlertSteps observations affirm a stopping rule under unrestricted sample size. Without dataGeneration, dataGenArgs, effectGeneration, and effectGenArgs no further data may be generated. If pre-generated data are insufficient for unrestricted monitoring, the user is notified to generate more data.

Under working knowledge of the data / clinical context, indicate the point null and clinical guideposts (2 guideposts for one-sided investigations and 4 guideposts for two-sided investigations). For a one-sided investigation, leave both of the lower (or upper) deltas (ie deltaL2 deltaL1 or deltaG1 deltaG2) set to NA.

To reduce false discoveries, the study waits until the interval of interest achieves an expected maximum width. The expected width assumes the standard deviation provided in dataGenArgs. Assuming larger variability than the truth yields a longer wait time and more conservative error.

Accruing data are monitored by intervals as specified with modelFit and modelFitArgs which may be user defined.

Monitoring rules: An alert is raised when the effect, theta, is ruled to be not trivial or not meaningful (using sgpv). To reduce bias, increase coverage, and improve operating characteristics in general, the study may require the same alert be raised A observations later (or prior). To investigate the ideal choice of A, user may specify lookSteps up until maxAlertSteps.

Note: User may choose to save the generated or pre-specified data. This can be substantive in size. However, when generating data from a location-shift family, it may be used to fully explore a range of shifted intervention effects (theta).

Usage

SeqSGPV(
  mcmcData = NULL,
  nreps,
  dataGeneration = rnorm,
  dataGenArgs = list(n = 200),
  effectGeneration = 0,
  effectGenArgs = NULL,
  effectScale = "identity",
  effectPN = 0,
  allocation,
  null = "two.sided",
  PRISM,
  modelFit,
  modelFitArgs = NULL,
  wait = 4,
  steps = 1,
  affirm = 0,
  lag = 0,
  N = NA,
  printProgress = TRUE,
  outData = TRUE,
  getECDF = TRUE,
  cores = NULL,
  fork = TRUE,
  socket = TRUE
)

Arguments

mcmcData	Previously generated data. Default (NULL) uses mcmc generation inputs to generate new or additional data.
nreps	Number of mcmc replicates to generate
dataGeneration	Function (such as rnorm) to generate outcomes.
dataGenArgs	Arguments for dataGeneration function. This includes, in the least, 'n' observations to generate. If 'n' is insufficient for unrestricted adaptive monitoring, additional data will be generated.
effectGeneration	Function (such as rnorm) or fixed value to generate intervention effect (theta).
effectGenArgs	Arguments for effectGeneration function (if any)
effectScale	Required transformation effect to generate data under dataGeneration. Can be any of 'identity', 'log', 'oddsratio', or 'or'.
effectPN	Point null of null hypothesis. For 1-sided hypotheses, it is the boundary of the null of greatest interest (ex: H0: mu <= 0, effectPN = 0).
allocation	A vector of the allocation ratio. For single arm trials, allocation is 1. For 2:3 allocation, set to c(2,3).
null	Any of "two.sided", "greater", "less" to specify the type of null hypothesis.
PRISM	A list with elements deltaL2, deltaL1, deltaG1, deltaG2. The lower, or upper, deltas may be set to NA to assess one- or two-sided hypotheses
modelFit	Function to obtain interval from data. Available functions for 1 and 2 armed trials include 'lmCI' and 'lrCI' which are respectively confidence intervals of a linear model and of a logistic regression (CI of odds ratio). Also, binomCI, uses binom::binom.confit for credible and confidence intervals of 1-armed trials with bernoulli outcomes.
modelFitArgs	List of inputs for modelFit function
wait	Vector of possible wait times (W) before monitoring.
steps	Vector of the number of observations (S) in between monitoring assessments.
affirm	Vector of the number of observations required for affirming a stopping rule (A) in between raising an alert of stopping.
lag	Vector of the number of delayed outcomes between enrolling a single observation and observing its outcome.
N	Vector of maximum sample size. Can be set as Inf (indefinite).
printProgress	Prints when adding more data for mcmc replicates to have sufficient observations to monitor until a conclusion. Defaults to TRUE.
outData	Returns the mcmc generated data. This can result in an out object with large memory. Yet, with location shift data, can be re-used to obtain operating characteristics of shifted effects.
getECDF	Returns the ECDF of sample size and bias for each wait width and number of steps before affirming end of study.
cores	Number of cores used in parallel computing. The default (NULL) does not run on parallel cores.
fork	Fork clustering, works on POSIX systems (Mac, Linux, Unix, BSD) and not Windows. Defaults to TRUE.
socket	Socket clustering. Defaults to TRUE yet only applies if FORK = FALSE.

Value

If effectGeneration is single value, returns list of class SeqSGPV which includes elements: mcmcMonitoring replicates (all generated data), mcmcOC (average operating characterstics for each combination of monitoring frequencies), mcmcECDFs (ecdf functions of sample size and bias for each combination of monitoring frequencies), and inputs (inputs into SeqSGPV).

If effectGeneration is a function, returns a list of class SeqSGPVre which includes elements: mcmcEOS (the final observation of each replicate for each combination of monitoring frequencies) and inputs (inputs into SeqSGPV).

chipmanj/SeqSGPV documentation built on May 1, 2024, 10:38 p.m.