| Title: | Simulation Tools for Planning Vitamin D Studies |
|---|---|
| Description: | Simulation tools for planning Vitamin D studies. Individual vitamin D status profiles are simulated, modelling population heterogeneity in trial arms. Exposures to infectious agents are generated, with infection depending on vitamin D status. |
| Authors: | Rebecca Mangan [aut], Jason Wyse [aut, cre], Lina Zgaga [aut] |
| Maintainer: | Jason Wyse <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.0.3 |
| Built: | 2024-11-12 03:24:53 UTC |
| Source: | https://github.com/cran/SimVitD |
A suite of tools for statistical planning of vitamin D trials.
The SimVitD package uses simulation to aid in statistical planning of vitamin D trials. The core elements of the simulation based tools involve
(i) simulation of an individual vitamin D staus profiles taking into account natural cyclic variation in summer and winter
(ii) simulation of exposures to potential infections in an individual's envrionment
(iii) simulation of the possibility of developing infection conditional on vitamin D status at exposure
(iv) Monte Carlo estimation of power of detecting supplementation effects for a selection of different supplementation scheme and two classes of hypothesis test.
The fuctions vitd.curve to generate individual status profiles and exposure.levels to simulate exposures. The accompanying vignette provides a gateway into the simulation tools.
Rebecca Mangan, Jason Wyse, Lina Zgaga
# simulate individual Vitamin D profiles indprofiles <- vitd.curve( n=10, type="placebo" ) # make a plot of all these profiles plot( indprofiles ) # intensity function for exposures to infection intensfun <- intensity.function( summer.rate=0.1, winter.rate=0.9 ) # exposure times expos <- exposure.levels( indprofiles, rate=2, intensfun, end=2 ) # plot of exposures on top of Vitamin D profiles plot( expos ) # disease calculation infect <- infection.count( expos ) # plot disease points on top of exposure points infection.count.plot( expos, infect )# simulate individual Vitamin D profiles indprofiles <- vitd.curve( n=10, type="placebo" ) # make a plot of all these profiles plot( indprofiles ) # intensity function for exposures to infection intensfun <- intensity.function( summer.rate=0.1, winter.rate=0.9 ) # exposure times expos <- exposure.levels( indprofiles, rate=2, intensfun, end=2 ) # plot of exposures on top of Vitamin D profiles plot( expos ) # disease calculation infect <- infection.count( expos ) # plot disease points on top of exposure points infection.count.plot( expos, infect )
exposure.levels creates a list of the exposures to an infectious agent and the status of vitamin D at the time of each exposure for each participant. The exposure times are simulated from a non homogeneous poisson process.
exposure.levels( x, rate, intensity.func = intensity.function(), start = 0, end = 1 )exposure.levels( x, rate, intensity.func = intensity.function(), start = 0, end = 1 )
x |
An object of class |
rate |
Expected number of exposures per week, the rate at which exposures occur in an equivalent homogeneous Poisson process. |
intensity.func |
A function that takes time as sole argument and returns value between 0 and 1, scaling the rate argument. For example, exposures may be higher at certain times for seasonal infections. |
start |
Start time of the study in units of years. |
end |
End time of study in units of years. |
exposure.levels returns an object of class exposure.levels that is a list.
The list has the following slots.
exposures |
The exposure times to infection for each participant. |
levels |
The vitamin D staus levels for each participant at the time of exposure to infection. |
Rebecca Mangan and Jason Wyse
Generates probabilities of developing infection, the relative risk and whether a participant becomes infected or not at exposure times.
infection.count( expos, baseline = 0.03, RR = 3, holding.time = 2, lohi.vit = c(10,70) )infection.count( expos, baseline = 0.03, RR = 3, holding.time = 2, lohi.vit = c(10,70) )
expos |
An object of class |
baseline |
Numeric, baseline prevalence of developing infection at any exposure time. Probability of developing infection when a participant has maximum (fully replete) vitamin D levels. |
RR |
Numeric, the relative risk of the study. The difference between becoming infected at highest and lowest vitamin D levels. |
holding.time |
Numeric, the mean number of weeks for after becoming infected when the participant can not become re-infected. Times are simulated independently from an exponential distribution with this mean. |
lohi.vit |
A vector of length 2 giving the level at which a participant is considered to have insufficient and sufficient vitamin D status levels. |
infection.count returns an object of class infection.count that is a list.
The list has the following slots.
baseline |
The baseline prevalence of disease. |
RR |
The relative risk of the study. |
inflection |
The inflection points of the relative risk curve. |
probs |
Matrix, the probability of developing infection at each exposure time for each participant. |
relativerisk |
Matrix, the relative risk of infection at each exposure time for each participant. |
infection |
Matrix, 1 if participant was infected at the corresponding exposure time, 0 if participant was not infected at exposure time. |
count |
Number of infections for each participant over the course of the study. |
mean |
The mean number of infections for the group over the course of the study. |
Rebecca Mangan and Jason Wyse
Plot whether a participant was disease or not as points on top of the vitamin D curves plotted from plot.vitd.curve.
infection.count.plot( expos, infect, pch = 20, cex = 1.5, col = "red" )infection.count.plot( expos, infect, pch = 20, cex = 1.5, col = "red" )
expos |
An object of class |
infect |
An object of class |
pch |
Plotting symbol for the points. |
cex |
Standard graphical parameter. |
col |
Colour of the plotted points. |
Rebecca Mangan and Jason Wyse
Generates intensity function, function with time as sole argument.
intensity.function( summer.rate = 0, winter.rate = 1, flu = TRUE )intensity.function( summer.rate = 0, winter.rate = 1, flu = TRUE )
summer.rate |
Value bwteeen 0 and 1, the rate at which exposures occur in summer months. |
winter.rate |
Value between 0 and 1, the rate at which exposures occur in winter months. |
flu |
If |
intensity.function returns a function that takes
time as sole argument and returns value between 0 and 1,
the returned function acts as
intensity.func for input to exposure.levels.
Rebecca Mangan and Jason Wyse
Plot the exposures to infection as points on top of the vitamin D curves plotted from plot.vitd.curve.
## S3 method for class 'exposure.levels' plot( x, col = "blue", ... )## S3 method for class 'exposure.levels' plot( x, col = "blue", ... )
x |
An object of class |
col |
Character, value for the colour of the points. |
... |
Additional arguments to be passed to the |
Rebecca Mangan and Jason Wyse
Plot the power between two groups as the number of participants and the relative risk vary.
## S3 method for class 'power.calc' plot( x, col = "hotpink", lwd = 1.5, lty = 1, ylab = NULL, x.legend = NULL, y.legend = NULL, main.legend = "Risk scaling", legend.size = 1, target.power = NA, which = 1L, ... )## S3 method for class 'power.calc' plot( x, col = "hotpink", lwd = 1.5, lty = 1, ylab = NULL, x.legend = NULL, y.legend = NULL, main.legend = "Risk scaling", legend.size = 1, target.power = NA, which = 1L, ... )
x |
An object of class |
col |
Colour of the line. |
lwd |
Line width. |
lty |
Line type. |
ylab |
Title for the y-axis. |
x.legend |
The x position of the legend. If not given, tries to default to a sensible value. |
y.legend |
The y position of the legend. If not given, tries to default to a sensible value. |
main.legend |
Title for the legend. |
legend.size |
Size of the legend. |
target.power |
Add a horizontal dotted line at a target power. A value of |
which |
Type of plot. Value 1 gives a plot of power, and value 2 plot of estimated effect size. |
... |
Additional arguments to be passed to the |
Rebecca Mangan and Jason Wyse
Plot vitamin D status curves.
## S3 method for class 'vitd.curve' plot( x, main = " ", xlab = " ", ylab = "25-hydroxyvitamin D", col=1:6, add = FALSE, ylim = NULL, ... )## S3 method for class 'vitd.curve' plot( x, main = " ", xlab = " ", ylab = "25-hydroxyvitamin D", col=1:6, add = FALSE, ylim = NULL, ... )
x |
An object of class |
main |
Main title for the plot. |
xlab |
A title for the x-axis. |
ylab |
A title for the y-axis. |
col |
A vector of colours for the plotted status curves. |
add |
If |
ylim |
Gives the plotting limits on tye y-axis. |
... |
Additional arguments to the |
Rebecca Mangan and Jason Wyse
generates a value for the power between two groups
power.calc( n, ratio=1, N = 500, test.type, sig.level = 0.05, vitdcurves.placebo = NULL, vitdcurves.treatment = NULL, baseline = 0.03, RR = 3, rate = 1, intensity.func = intensity.function(), holding.time = 2, lohi.vit = c(10,70), clt = NULL, mc.error = 1, boot.rep = 9999, parallel = FALSE, num.cores = NULL, verbose=FALSE )power.calc( n, ratio=1, N = 500, test.type, sig.level = 0.05, vitdcurves.placebo = NULL, vitdcurves.treatment = NULL, baseline = 0.03, RR = 3, rate = 1, intensity.func = intensity.function(), holding.time = 2, lohi.vit = c(10,70), clt = NULL, mc.error = 1, boot.rep = 9999, parallel = FALSE, num.cores = NULL, verbose=FALSE )
n |
Numeric, the number of participants in the control group. |
ratio |
Ratio greater than or equal to 1 giving size of treatment group as a multiple of |
N |
Number of simulations of the study to run. |
test.type |
Type of test to calculate the power, one of "count" or "proportions". |
sig.level |
Significance level used to test for a statistically significant difference between the groups. |
vitdcurves.placebo |
An object of class |
vitdcurves.treatment |
An object of class |
baseline |
Baseline prevalence of getting diseased at any exposure time. Probability of getting diseased when a participant has sufficient vitamin D levels. |
RR |
Fold risk difference between getting infection between the most deficient and most sufficient vitamin D levels. |
rate |
Expected number of exposures per week, the rate at which exposures occur in the equivalent homogeneous Poisson process. |
intensity.func |
Function taking time as sole argument and returns value between 0 and 1, input to nhpp function see poisson package. |
holding.time |
Expected number of weeks for the holding time. |
lohi.vit |
Inflection points of the relative risk curve used in |
clt |
Logical or vector of logical values of same length as |
mc.error |
Number of times to repeat the experiment at each |
boot.rep |
Number of bootstrap samples to carry out non-parametric tests of hypotheses. |
parallel |
Use parallel processing to carry out the simulations. This will parallelise over mc.error. |
num.cores |
Number of cores to exploit in parallel mode. Defaults to (cores available) - 1. |
verbose |
If |
power.calc returns an object of class power.calc that is a list.
The list has the following slots.
test.type |
The type of study the power has been calculated on. |
baseline |
The baseline prevalence for disease. |
RR |
The relative risk of the study. |
npergroup |
The number of participants per group in the study. |
mc.error |
Number of repetitions of experiment to approximate Monte Carlo error. |
power |
A |
eff.size |
A |
Rebecca Mangan and Jason Wyse
# simulate placebo group placebo <- vitd.curve( n = 10, type = "placebo" ) # simulate treatment group treatment <- vitd.curve( n = 10, type = "dynamic-dose" ) # intensity function for exposures to infection intensfun <- intensity.function( summer.rate = 0, winter.rate = 1 ) # calculate power: example only- run for much larger value of N pow <- power.calc( n = c(10,20,30), N = 10, test.type = 'count', vitdcurves.placebo = placebo, vitdcurves.treatment = treatment, baseline = 0.03, RR = c(2,4), rate = 1, intensity.func = intensfun, boot.rep=2000 ) ### NOT RUN ### # approximate the Monte Carlo error in estimation of the power-- takes longer to run #pow <- power.calc( n = c(10,20,30), # N = 100, test.type = 'count', # vitdcurves.placebo = placebo, vitdcurves.treatment = treatment, # baseline = 0.03, RR = c(2,3,4), rate = 1, # intensity.func = intensfun, mc.error = 10 ) # plot power curves plot( pow, xlab = "n", x.legend = 10, y.legend = 1, main.legend = "Relative Risk" )# simulate placebo group placebo <- vitd.curve( n = 10, type = "placebo" ) # simulate treatment group treatment <- vitd.curve( n = 10, type = "dynamic-dose" ) # intensity function for exposures to infection intensfun <- intensity.function( summer.rate = 0, winter.rate = 1 ) # calculate power: example only- run for much larger value of N pow <- power.calc( n = c(10,20,30), N = 10, test.type = 'count', vitdcurves.placebo = placebo, vitdcurves.treatment = treatment, baseline = 0.03, RR = c(2,4), rate = 1, intensity.func = intensfun, boot.rep=2000 ) ### NOT RUN ### # approximate the Monte Carlo error in estimation of the power-- takes longer to run #pow <- power.calc( n = c(10,20,30), # N = 100, test.type = 'count', # vitdcurves.placebo = placebo, vitdcurves.treatment = treatment, # baseline = 0.03, RR = c(2,3,4), rate = 1, # intensity.func = intensfun, mc.error = 10 ) # plot power curves plot( pow, xlab = "n", x.legend = 10, y.legend = 1, main.legend = "Relative Risk" )
Print a summary of a exposure.levels object.
## S3 method for class 'exposure.levels' print( x, ... )## S3 method for class 'exposure.levels' print( x, ... )
x |
An object of class |
... |
Optional arguments to lower level functions. |
Rebecca Mangan and Jason Wyse
Print a summary of a infection.count object.
## S3 method for class 'infection.count' print( x, ... )## S3 method for class 'infection.count' print( x, ... )
x |
An object of class |
... |
Optional arguments to lower level functions. |
Rebecca Mangan and Jason Wyse
Print a summary of a power.calc object.
## S3 method for class 'power.calc' print( x, ... )## S3 method for class 'power.calc' print( x, ... )
x |
An object of class |
... |
Optional arguments to lower level functions. |
Rebecca Mangan and Jason Wyse
Print a summary of a vitd.curve object.
## S3 method for class 'vitd.curve' print( x, ... )## S3 method for class 'vitd.curve' print( x, ... )
x |
An object of class |
... |
Optional arguments to lower level functions. |
Rebecca Mangan and Jason Wyse
Plot the relative risk curve for vitamin D showing times of exposure and whether a participant developed infection from exposure.
rr.curve.plot( expos, infect, idx = 1, main = NULL, xlab = "25-hydroxyvitamin D", ylab = "Risk scaling", col = "blue", ... )rr.curve.plot( expos, infect, idx = 1, main = NULL, xlab = "25-hydroxyvitamin D", ylab = "Risk scaling", col = "blue", ... )
expos |
An object of class |
infect |
An object of class |
idx |
A vector of indexes of specific exposures to plot. |
main |
Main title for the plot. |
xlab |
A title for the x-axis. |
ylab |
A title for the y-axis. |
col |
Character, value for the colour of the points. |
... |
Additional arguments to |
Rebecca Mangan and Jason Wyse
Plot a vitamin D status profile for a single participant and the relative risk curve for vitamin D (with exposure times and whether a participant was infected at that exposure time) side by side.
rr.profile.plot( x, expos, infect, idx = 1, ... )rr.profile.plot( x, expos, infect, idx = 1, ... )
x |
An object of class |
expos |
An object of class |
infect |
An object of class |
idx |
Index of curve to plot. |
... |
Additional arguments to |
Rebecca Mangan and Jason Wyse
# individual profiles indprofiles <- vitd.curve( n=10, type="placebo" ) # intensity function for exposures to infection intensfun <- intensity.function( summer.rate=0.1, winter.rate=0.9 ) # exposure times expos <- exposure.levels( indprofiles, rate=2, intensfun, end=2 ) # disease calculation infect <- infection.count( expos ) # plot RR profile rr.profile.plot( indprofiles, expos, infect )# individual profiles indprofiles <- vitd.curve( n=10, type="placebo" ) # intensity function for exposures to infection intensfun <- intensity.function( summer.rate=0.1, winter.rate=0.9 ) # exposure times expos <- exposure.levels( indprofiles, rate=2, intensfun, end=2 ) # disease calculation infect <- infection.count( expos ) # plot RR profile rr.profile.plot( indprofiles, expos, infect )
Print a summary of a exposure.levels object.
## S3 method for class 'exposure.levels' summary( object, ... )## S3 method for class 'exposure.levels' summary( object, ... )
object |
An object of class |
... |
Optional arguments to lower level functions. |
Rebecca Mangan and Jason Wyse
Print a summary of a infection.count object.
## S3 method for class 'infection.count' summary( object, ... )## S3 method for class 'infection.count' summary( object, ... )
object |
An object of class |
... |
Optional arguments to lower level functions. |
Rebecca Mangan and Jason Wyse
Print a summary of a power.calc object.
## S3 method for class 'power.calc' summary( object, ... )## S3 method for class 'power.calc' summary( object, ... )
object |
An object of class |
... |
Optional arguments to lower level functions. |
Rebecca Mangan and Jason Wyse
Print a summary of a vitd.curve object.
## S3 method for class 'vitd.curve' summary( object, ... )## S3 method for class 'vitd.curve' summary( object, ... )
object |
An object of class |
... |
Optional arguments to lower level functions. |
Rebecca Mangan and Jason Wyse
Generates a vitamin D status profile curve for each individual in a group
vitd.curve( n = 1, type = c("placebo","fixed-dose","dynamic-dose"), start = 0, end = 1, mu = 45, amplitude = 35, dyn.dose.thresh = 50, sd.mu = 5, sd.amplitude = 5, sd.dyn.dose.thresh = 5, supp.dose = 20, supp.dose.rate = Inf, weight = 1, sd.weight = 0, min.thresh = 10, north.hemi = TRUE, res = 40 )vitd.curve( n = 1, type = c("placebo","fixed-dose","dynamic-dose"), start = 0, end = 1, mu = 45, amplitude = 35, dyn.dose.thresh = 50, sd.mu = 5, sd.amplitude = 5, sd.dyn.dose.thresh = 5, supp.dose = 20, supp.dose.rate = Inf, weight = 1, sd.weight = 0, min.thresh = 10, north.hemi = TRUE, res = 40 )
n |
Number of curves to simulate. |
type |
One of "placebo", "fixed-dose", "dynamic-dose". |
start |
Time in units of years when trial started. |
end |
Time in units of years when trial ended. |
mu |
The mean level of 25OHD in the trial arm around which there is cosine variation. |
amplitude |
Amplitude of cosine function describing variation around |
dyn.dose.thresh |
Threshold for the concentration-controlled scheme. |
sd.mu |
Standard deviation levels around mean; this is the standard deviation of H in vignette. |
sd.amplitude |
Standard deviation of the amplitude. |
sd.dyn.dose.thresh |
Standard deviation of the participant retained concentration in the concentration-controlled trial. |
supp.dose |
The 25OHD nmol/l equivalent for dosage in fixed-dose supplementation. |
supp.dose.rate |
Concentration parameter for fixed-dose scheme uptake. Large values imply that all participants derive the same equivalent. |
weight |
For fixed-dose supplementation, this is the expected value of the proportion of the dose which is always utilized. |
sd.weight |
Standard deviation of weight |
min.thresh |
The minimum detectable threshold of 25OHD. Defaults to 10 nmol/l. |
north.hemi |
Summer/winter months as in the Northern Hemisphere if |
res |
Resolution parameter for plotting of vitamin D curves. |
vitd.curve returns an object of class vitd.curve. Curve parameter settings are returned. The slot curves give the curve specific parameters for each of the n generated curves. Additionally, time used for plotting gives time values passed to plot.vitd.curve.
Rebecca Mangan and Jason Wyse