Package 'fidelitysim'

Title: Fidelity patterns in simulation experiments for cluster randomized trials in implementation science research
Description: The package provides functions to coduct simulation experiments for investigating the performance of effect estimation within parallel/stepped-wedged cluster randomized trials under consideration of implementation error (measured by fidelity).
Authors: Diana Trutschel [aut] , Catherine Blatter [ctb, cre]
Maintainer: Catherine Blatter <[email protected]>
License: CC BY 4.0
Version: 0.1.1
Built: 2025-02-17 05:30:56 UTC
Source: https://github.com/INS-Basel/fidelitysim

Help Index

Get bias estimate

Description

Calculation of performance measure of estimation: Bias as the difference between the estimated and actual values

Usage

bias(vec, theta)

Arguments

vec

Estimated value from simulation
theta

True value

Value

Bias of effect estimation

Approximate within points

Description

Calculation of all points in between a given start point and end point for a given total number of points

Usage

calc.X.values(x.B, x.E, time.points)

Arguments

x.B

starting point (begin)
x.E

end point
time.points

number of points on total

Value

all exact points

Data loss simulation for given study data

Description

Simulate a loss of data points within a full study data obtained within I clusters and observed over K time points

Usage

Data.loss.SWD(data.all, I, K, B = "0", C = 0, D = 0)

Arguments

data.all

given data of a study (can be simulated or obtained)
I

Number of clusters within the study
K

Number of time points within the study
B

Type of cluster loss: 0 = No cluster loss, 1 = Cluster missing at random, 2 = Cluster is missing at beginning, 3 = Cluster is missing at end of the study
C

Number of clusters which getting lost
D

Number of individual loss (chosen randomly from all individuals within the study)

Value

Matrix of data which is remained after data loss

Find approximate fidelity with an exponential function

Description

Calculates for given start Fidelity and end Fidelity the within Fidelity for a given number of time points using an exponential function, where with the par.slope stretching and compression of the function can be influenced. Here the exponential function is derived as the reflection of the logarithm function on the straight line par.slope has to be greater than 0, near zero then the values are almost constant, the greater then the values are going against the linear line

Usage

find.Fidelity.exp(time.points, Fid.End, Fid.T1, par.slope = 1)

Arguments

time.points

number of time points
Fid.End

Fidelity at the end (final time point)
Fid.T1

Fidelity at the begin (starting time point)
par.slope

Slope for the logarithmic function has to be greater 0, the greater towards 1 the more linear is the function

Value

a matrix: first column with time points, second column corresponding Fidelity for the time points

Find approximate fidelity with a linear function

Description

calculates for given start Fidelity and end Fidelity the within Fidelity for a given number of time points using a linear function

Usage

find.Fidelity.linear(time.points, Fid.End, Fid.T1)

Arguments

time.points

number of time points
Fid.End

Fidelity at the end (final time point)
Fid.T1

Fidelity at the begin (starting time point)

Value

a matrix: first column with time points, second column corresponding Fidelity for the time points

Find approximate fidelity with a logarithmic function

Description

Calculates for given start Fidelity and end Fidelity the within Fidelity for a given number of time points using a logarithmic function to approximate Fidelity in between, where with the par.slope stretching and compression of the function can be influenced. par.slope has to be greater than 0, near zero then the values are almost constant, the greater then the values are going against the linear line.

Usage

find.Fidelity.log(time.points, Fid.End, Fid.T1, par.slope = 1)

Arguments

time.points

number of time points
Fid.End

Fidelity at the end (final time point)
Fid.T1

Fidelity at the begin (starting time point)
par.slope

Slope for the logarithmic function has to be greater 0, the greater towards 1 the more linear is the function

Value

a matrix: first column with time points, second column corresponding Fidelity for the time points

Implementation of crossover matrix

Description

Given a design of a hypothetical cluster randomized stepped wedge study and their pattern of fidelity over time conduct the function the corresponding design matrix which can be used for linear regression modeling

Usage

implemMatrix.crossover(nC, nT, nSw, swP = NULL, pattern)

Arguments

nC

Number of cluster
nT

Number of time points
nSw

Number of cluster with switches from control condition 0 to treatment condition 1 at each time point
swP

Number of timepoints the for clusters be at control
pattern

Fidelity pattern (deviation from 1) for each time point

Value

Design matrix of size nT x nC for a cross-over cluster randomized trial with values of 0 for control condition and values between 0 and 1 for degree of implementation of treatment (fidelity)' @return

Implementation of parallel matrix

Description

Given a design of a hypothetical cluster parallel randomized study and their pattern of fidelity over time conduct the function the corresponding design matrix which can be used for linear regression modeling

Usage

implemMatrix.parallel(nC, nT, nSw, pattern)

Arguments

nC

Number of cluster
nT

Number of time points
nSw

Number of cluster with control condition 0 (nC-nSw is then the number of cluster with treatment condition 1)
pattern

Fidelity pattern (deviation from 1) for each time point

Value

Design matrix of size nT x nC for a parrallel cluster randomized trial with values of 0 for control condition and values between 0 and 1 for degree of implementation of treatment (fidelity)

Get several performance measures of (effect estimation) simulation studies

Description

Calculation of several performance measure for the estimates obtained from the simulation repeats

Usage

performanceMeas(vecEst, vecSe, vec.p, theta, alpha = 0.05)

Arguments

vecEst

vector of estimated effect values from simulation repeats
vecSe

vector of estimated standard error from simulation repeats
vec.p

vector of significance (probability of being sampled from null hypothesis) from simulation repeats
theta

true value for effect
alpha

Type I error rate = significance level for testing the null hypothesis

Value

Vector of Performance measures:

  1. Average of the estimates of the parameter of interest

  2. Empirical standard error as an assessment of the estimation uncertainty

  3. Bias = mean deviation of the estimates from the true value of the parameter of interest is an indicator of accuracy

  4. Coverage of a confidence interval is a measurement that can be used to control the Type I error

  5. Empirical power = the proportion of simulation samples in which the H0 of no effect is rejected at a significance level when H0 is false

Get performance measures from effect estimation within all repeats of the simulation

Description

Simulation for ?????? Repeats anzSim times the following steps

  1. Determining the design matrix regarding the chosen design (Design, Number of cluster, time points, individuals) knowing Fidelity pattern and possible data loss

  2. Sample data of the given study design and expected data loss using the package "samplingDataCRT"

  3. Estimation of Effects using linear mixed model estimation

Usage

simulation(
  anzSim,
  type,
  sigma.1,
  sigma.2 = NULL,
  sigma.3,
  K,
  J,
  I,
  mu.0,
  theta,
  betas,
  X,
  X.A,
  B.cond = "0",
  C.cond = 0,
  D.cond = 0
)

Arguments

anzSim

Number of simulation repeats
type

Study design type = "cross-sec" for cross-sectional or "long" for longitudinal
sigma.1

Within variability or error variance (Hughes&Hussey sigma)
sigma.2

Between individual variance (only used when the individuals are followed over time: longitudinal study)
sigma.3

Between clusters variability (Hughes&Hussey tau)
K

Number of time points (measurement)
J

Number of Individuals (=individuals per cluster)
I

Number of cluster
mu.0

Baseline mean within the model specification
theta

Intervention effect
betas

Time trend could be included
X

Design matrix for building linear model of given ooptimal study
X.A

Design matrix for building linear model of sampling real data given real setting
B.cond

Condition for type of cluster loss: 0 = No cluster loss, 1 = Cluster missing at random, 2 = Cluster is missing at beginning, 3 = Cluster is missing at end of the study
C.cond

Condition for number of clusters which getting lost
D.cond

Condition for Number of individual loss (chosen randomly from all individuals within the study)

Value

Vector of Estimates summaru=ies and performance measures (see function performanceMeas):

  1. Average of the estimates of the parameter of interest

  2. Empirical standard error as an assessment of the estimation uncertainty

  3. Bias = mean deviation of the estimates from the true value of the parameter of interest is an indicator of accuracy

  4. Coverage of a confidence interval is a measurement that can be used to control the Type I error

  5. Empirical power = the proportion of simulation samples in which the H0 of no effect is rejected at a significance level when H0 is false

See Also

Reference for linear model formulation of stepped wedge cluster randomized trials by Hussey and Hughes "Design and analysis of stepped wedge cluster randomized trials", Contemporary Clinical Trials, 2007 https://www.sciencedirect.com/science/article/pii/S1551714406000632 as well as performance measurements for simulation studies by Burton et al. “The design of simulation studies in medical statistics”, Stat Med, 2006 https://pubmed.ncbi.nlm.nih.gov/16947139/