}}\preformatted{biokinetics$simulate_population_trajectories(
time_type = "relative",
t_max = 150,
summarise = TRUE,
@@ -169,12 +169,12 @@ titre_type and a column for each covariate in the hierarchical model. See the da
}
}
\if{html}{\out{
}}
-\if{latex}{\out{\hypertarget{method-scova-population_stationary_points}{}}}
+\if{html}{\out{
}}
+\if{latex}{\out{\hypertarget{method-biokinetics-population_stationary_points}{}}}
\subsection{Method \code{population_stationary_points()}}{
Process the stan model results into a data.table.
\subsection{Usage}{
-\if{html}{\out{
}}\preformatted{scova$population_stationary_points(n_draws = 2500)}\if{html}{\out{
}}\preformatted{biokinetics$population_stationary_points(n_draws = 2500)}\if{html}{\out{
}}
}
\subsection{Arguments}{
@@ -191,13 +191,13 @@ mu_s_me, and a column for each covariate. See the data vignette for details:
}
}
\if{html}{\out{
}}
-\if{latex}{\out{\hypertarget{method-scova-simulate_individual_trajectories}{}}}
+\if{html}{\out{
}}
+\if{latex}{\out{\hypertarget{method-biokinetics-simulate_individual_trajectories}{}}}
\subsection{Method \code{simulate_individual_trajectories()}}{
Simulate individual trajectories from the model. This is
computationally expensive and may take a while to run if n_draws is large.
\subsection{Usage}{
-\if{html}{\out{
}}\preformatted{scova$simulate_individual_trajectories(
+\if{html}{\out{
}}\preformatted{biokinetics$simulate_individual_trajectories(
summarise = TRUE,
n_draws = 2500,
time_shift = 0
diff --git a/man/scova_priors.Rd b/man/biokinetics_priors.Rd
similarity index 61%
rename from man/scova_priors.Rd
rename to man/biokinetics_priors.Rd
index 0b9525c..306c3f0 100644
--- a/man/scova_priors.Rd
+++ b/man/biokinetics_priors.Rd
@@ -1,10 +1,10 @@
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/priors.R
-\name{scova_priors}
-\alias{scova_priors}
-\title{Construct priors for the SARS-CoV-2 antibody model.}
+\name{biokinetics_priors}
+\alias{biokinetics_priors}
+\title{Construct priors for the biomarker model.}
\usage{
-scova_priors(
+biokinetics_priors(
mu_values = c(4, 10, 60, 0.25, -0.02, 0),
sigma_values = c(2, 2, 3, 0.01, 0.01, 0.01)
)
@@ -15,15 +15,15 @@ scova_priors(
\item{sigma_values}{Standard deviation of Gaussian prior for each of t0, tp, ts, m1, m2, m3, in order.}
}
\value{
-A named list of type 'scova_priors'.
+A named list of type 'biokinetics_priors'.
}
\description{
-The scova model has 6 parameters: t0, tp, ts, m1, m2, m3 corresponding to critical time points and
+The biokinetics model has 6 parameters: t0, tp, ts, m1, m2, m3 corresponding to critical time points and
gradients. See the model vignette for details: \code{vignette("model", package = "epikinetics")}. Each of these
parameters has a Gaussian prior, and these can be specified by the user. This function takes means and standard
-deviations for each prior and constructs an object of type 'scova_priors' to be passed to the model.
+deviations for each prior and constructs an object of type 'biokinetics_priors' to be passed to the model.
}
\examples{
-priors <- scova_priors(mu_values = c(4.0, 10, 60, 0.25, -0.02, 0),
+priors <- biokinetics_priors(mu_values = c(4.0, 10, 60, 0.25, -0.02, 0),
sigma_values = c(2.0, 2.0, 3.0, 0.01, 0.01, 0.01))
}
diff --git a/tests/testthat/test-data.R b/tests/testthat/test-data.R
index 513e6fa..3ef31cf 100644
--- a/tests/testthat/test-data.R
+++ b/tests/testthat/test-data.R
@@ -8,8 +8,8 @@ local_mocked_bindings(
test_that("Can construct stan data", {
dt <- data.table::fread(system.file("delta_full.rds", package = "epikinetics"))
- mod <- scova$new(data = dt,
- priors = scova_priors(),
+ mod <- biokinetics$new(data = dt,
+ priors = biokinetics_priors(),
covariate_formula = ~0 + infection_history,
preds_sd = 0.25,
time_type = "relative")
@@ -20,12 +20,12 @@ test_that("Can construct stan data", {
})
test_that("Can initialise file path data", {
- expect_true(inherits(scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
- priors = scova_priors()), "scova"))
+ expect_true(inherits(biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ priors = biokinetics_priors()), "biokinetics"))
})
test_that("Can provide data directly", {
dat <- data.table::fread(system.file("delta_full.rds", package = "epikinetics"))
- expect_true(inherits(scova$new(data = dat,
- priors = scova_priors()), "scova"))
+ expect_true(inherits(biokinetics$new(data = dat,
+ priors = biokinetics_priors()), "biokinetics"))
})
diff --git a/tests/testthat/test-extract-parameters.R b/tests/testthat/test-extract-parameters.R
index 1690e5b..de0e955 100644
--- a/tests/testthat/test-extract-parameters.R
+++ b/tests/testthat/test-extract-parameters.R
@@ -7,17 +7,17 @@ local_mocked_bindings(
)
test_that("Cannot retrieve population params until model is fitted", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"))
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"))
expect_error(mod$extract_population_parameters(), "Model has not been fitted yet. Call 'fit' before calling this function.")
})
test_that("Cannot retrieve individual params until model is fitted", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"))
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"))
expect_error(mod$extract_individual_parameters(), "Model has not been fitted yet. Call 'fit' before calling this function.")
})
test_that("Can extract population parameters without human readable covariates", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
params <- mod$extract_population_parameters(n_draws = 10, human_readable_covariates = FALSE)
@@ -26,7 +26,7 @@ test_that("Can extract population parameters without human readable covariates",
})
test_that("Can extract population parameters with human readable covariates", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
params <- mod$extract_population_parameters(n_draws = 10, human_readable_covariates = TRUE)
@@ -36,7 +36,7 @@ test_that("Can extract population parameters with human readable covariates", {
})
test_that("Can extract individual parameters without human readable covariates", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
params <- mod$extract_individual_parameters(n_draws = 10,
@@ -47,7 +47,7 @@ test_that("Can extract individual parameters without human readable covariates",
})
test_that("Can extract individual parameters with human readable covariates", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
params <- mod$extract_individual_parameters(n_draws = 10,
@@ -58,7 +58,7 @@ test_that("Can extract individual parameters with human readable covariates", {
})
test_that("Can extract individual parameters with variation params", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
params <- mod$extract_individual_parameters(n_draws = 10,
diff --git a/tests/testthat/test-input-validation.R b/tests/testthat/test-input-validation.R
index 4242d0c..d67aa79 100644
--- a/tests/testthat/test-input-validation.R
+++ b/tests/testthat/test-input-validation.R
@@ -1,41 +1,41 @@
test_that("One of data or file required", {
- expect_error(scova$new(), "One of 'data' or 'file_path' must be provided")
+ expect_error(biokinetics$new(), "One of 'data' or 'file_path' must be provided")
})
test_that("Only one of data or file can be provided", {
- expect_error(scova$new(data = data.table::data.table(), file_path = "some/where"),
+ expect_error(biokinetics$new(data = data.table::data.table(), file_path = "some/where"),
"Only one of 'data' or 'file_path' should be provided")
})
-test_that("Priors must be of type 'scova_priors'", {
- expect_error(scova$new(priors = list(t0 = 1, t2 = 3)),
- "'priors' must be of type 'scova_priors'")
+test_that("Priors must be of type 'biokinetics_priors'", {
+ expect_error(biokinetics$new(priors = list(t0 = 1, t2 = 3)),
+ "'priors' must be of type 'biokinetics_priors'")
})
test_that("preds_sd must be numeric", {
- expect_error(scova$new(preds_sd = "bad"),
+ expect_error(biokinetics$new(preds_sd = "bad"),
"'preds_sd' must be numeric")
})
test_that("Time type must be 'absolute' or 'relative'", {
- expect_error(scova$new(time_type = "bad"),
+ expect_error(biokinetics$new(time_type = "bad"),
"'time_type' must be one of 'relative' or 'absolute'")
})
test_that("Covariate formula must be a formula", {
dat <- data.table(test = 1)
- expect_error(scova$new(data = dat, covariate_formula = "bad"),
+ expect_error(biokinetics$new(data = dat, covariate_formula = "bad"),
"'covariate_formula' must be a formula")
})
test_that("Covariates must be present in data", {
dat <- data.table(test = 1)
- expect_error(scova$new(data = dat, covariate_formula = 0~ bad),
+ expect_error(biokinetics$new(data = dat, covariate_formula = 0~ bad),
"All variables in 'covariate_formula' must correspond to data columns. Found unknown variables: bad")
})
test_that("Data must be a data.table", {
dat <- data.frame(test = 1)
- expect_error(scova$new(data = dat),
+ expect_error(biokinetics$new(data = dat),
"'data' must be a data.table")
})
diff --git a/tests/testthat/test-population-stationary-points.R b/tests/testthat/test-population-stationary-points.R
index 2e343c1..668dc3b 100644
--- a/tests/testthat/test-population-stationary-points.R
+++ b/tests/testthat/test-population-stationary-points.R
@@ -7,12 +7,12 @@ local_mocked_bindings(
)
test_that("Cannot retrieve data until model is fitted", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"))
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"))
expect_error(mod$population_stationary_points(), "Model has not been fitted yet. Call 'fit' before calling this function.")
})
test_that("Can get population stationary poins", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
result <- mod$population_stationary_points()
diff --git a/tests/testthat/test-priors.R b/tests/testthat/test-priors.R
index 095c621..881d809 100644
--- a/tests/testthat/test-priors.R
+++ b/tests/testthat/test-priors.R
@@ -6,9 +6,9 @@ test_that("Can construct named list of Gaussian prior parameters", {
})
test_that("Can construct cab prior parameters", {
- priors <- scova_priors(mu_values = c(1, 2, 3, 4, 5, 6), sigma_values = c(7, 8, 9, 10, 11, 12))
+ priors <- biokinetics_priors(mu_values = c(1, 2, 3, 4, 5, 6), sigma_values = c(7, 8, 9, 10, 11, 12))
expect_s3_class(priors, "gaussian_priors")
- expect_s3_class(priors, "scova_priors")
+ expect_s3_class(priors, "biokinetics_priors")
expect_true(is.list(priors))
expect_equal(unclass(priors), list("mu_t0" = 1, "mu_tp" = 2, "mu_ts" = 3,
"mu_m1" = 4, "mu_m2" = 5, "mu_m3" = 6,
diff --git a/tests/testthat/test-run-model.R b/tests/testthat/test-run-model.R
index 0c45b73..545a746 100644
--- a/tests/testthat/test-run-model.R
+++ b/tests/testthat/test-run-model.R
@@ -7,8 +7,8 @@ local_mocked_bindings(
)
test_that("Can fit model with arguments", {
- res <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
- priors = scova_priors())$fit(chains = 4,
+ res <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ priors = biokinetics_priors())$fit(chains = 4,
parallel_chains = 4,
iter_warmup = 100,
iter_sampling = 400,
diff --git a/tests/testthat/test-simulate-individual-trajectories.R b/tests/testthat/test-simulate-individual-trajectories.R
index 208e54d..9fbaf89 100644
--- a/tests/testthat/test-simulate-individual-trajectories.R
+++ b/tests/testthat/test-simulate-individual-trajectories.R
@@ -8,7 +8,7 @@ test_that("Cpp and R function produce same values", {
m2 = 1,
m3 = 1.5
)
- res_pop <- dat_pop[, mu := scova_simulate_trajectory(t, t0, tp, ts, m1, m2, m3), by = "t"]
+ res_pop <- dat_pop[, mu := biokinetics_simulate_trajectory(t, t0, tp, ts, m1, m2, m3), by = "t"]
dat_ind <- data.table(stan_id = 1L,
t_max = t_max,
k = 3L,
@@ -21,7 +21,7 @@ test_that("Cpp and R function produce same values", {
m3_ind = 1.5
)
- res_ind <- scova_simulate_trajectories(dat_ind)
+ res_ind <- biokinetics_simulate_trajectories(dat_ind)
expect_equal(res_pop$mu, res_ind$mu)
})
@@ -34,12 +34,12 @@ local_mocked_bindings(
)
test_that("Cannot retrieve trajectories until model is fitted", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"))
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"))
expect_error(mod$simulate_individual_trajectories(), "Model has not been fitted yet. Call 'fit' before calling this function.")
})
test_that("Validates inputs", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
expect_error(mod$simulate_individual_trajectories(summarise = "bad"), "'summarise' must be logical")
@@ -48,7 +48,7 @@ test_that("Validates inputs", {
})
test_that("Can retrieve summarised trajectories", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
trajectories <- mod$simulate_individual_trajectories(summarise = TRUE, n_draws = 10)
@@ -56,7 +56,7 @@ test_that("Can retrieve summarised trajectories", {
})
test_that("Can retrieve un-summarised trajectories", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
trajectories <- mod$simulate_individual_trajectories(summarise = FALSE, n_draws = 10)
@@ -65,7 +65,7 @@ test_that("Can retrieve un-summarised trajectories", {
})
test_that("Only n_draws draws are returned", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
trajectories <- mod$simulate_individual_trajectories(summarise = FALSE, n_draws = 10)
@@ -73,7 +73,7 @@ test_that("Only n_draws draws are returned", {
})
test_that("Exposure dates are brought forward by time_shift days", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
trajectories <- mod$simulate_individual_trajectories(summarise = FALSE, n_draws = 10)
diff --git a/tests/testthat/test-simulate-population-trajectories.R b/tests/testthat/test-simulate-population-trajectories.R
index cf69004..cc0addb 100644
--- a/tests/testthat/test-simulate-population-trajectories.R
+++ b/tests/testthat/test-simulate-population-trajectories.R
@@ -7,12 +7,12 @@ local_mocked_bindings(
)
test_that("Cannot retrieve trajectories until model is fitted", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"))
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"))
expect_error(mod$simulate_population_trajectories(), "Model has not been fitted yet. Call 'fit' before calling this function.")
})
test_that("Validates inputs", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
expect_error(mod$simulate_population_trajectories(summarise = "bad"), "'summarise' must be logical")
@@ -22,7 +22,7 @@ test_that("Validates inputs", {
})
test_that("Can retrieve summarised trajectories", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
trajectories <- mod$simulate_population_trajectories(summarise = TRUE)
@@ -30,7 +30,7 @@ test_that("Can retrieve summarised trajectories", {
})
test_that("Can retrieve un-summarised trajectories", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
trajectories <- mod$simulate_population_trajectories(summarise = FALSE)
@@ -40,7 +40,7 @@ test_that("Can retrieve un-summarised trajectories", {
})
test_that("Absolute dates are returned if time_type is 'absolute'", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
trajectories <- mod$simulate_population_trajectories(summarise = TRUE, time_type = "absolute")
@@ -49,7 +49,7 @@ test_that("Absolute dates are returned if time_type is 'absolute'", {
})
test_that("Only times up to t_max are returned", {
- mod <- scova$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
+ mod <- biokinetics$new(file_path = system.file("delta_full.rds", package = "epikinetics"),
covariate_formula = ~0 + infection_history)
mod$fit()
trajectories <- mod$simulate_population_trajectories(summarise = TRUE, t_max = 10)
diff --git a/vignettes/scova.Rmd b/vignettes/biokinetics.Rmd
similarity index 90%
rename from vignettes/scova.Rmd
rename to vignettes/biokinetics.Rmd
index 026c159..88e7d42 100644
--- a/vignettes/scova.Rmd
+++ b/vignettes/biokinetics.Rmd
@@ -1,8 +1,8 @@
---
-title: "SARS-CoV-2 antibody model: replicating paper figures"
+title: "biokinetics case study"
output: rmarkdown::html_vignette
vignette: >
- %\VignetteIndexEntry{SARS-CoV-2 antibody model: replicating paper figures}
+ %\VignetteIndexEntry{biokinetics case study}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
@@ -14,15 +14,20 @@ knitr::opts_chunk$set(
)
```
+The underlying `biokinetics` model was developed in the following paper:
+[Russell TW et al. Real-time estimation of immunological responses against emerging SARS-CoV-2 variants in the UK: a mathematical modelling study. Lancet Infect Dis. 2024 Sep 11:S1473-3099(24)00484-5](https://doi.org/10.1016/s1473-3099(24)00484-5)
+
+This vignette demonstrates how to use the `epikinetics` package to replicate some of the key paper figures.
+
# Fitting the model
-To initialise a model object, the only required argument is a path to the data in CSV format, or a [data.table]("https://cran.r-project.org/web/packages/data.table/index.html"). See [scova](../reference/scova.html) for all available arguments. In this vignette we use a dataset representing the Delta wave which is installed with this package, specifying a hierarchical model that just looks at the effect of infection history.
+To initialise a model object, the only required argument is a path to the data in CSV format, or a [data.table]("https://cran.r-project.org/web/packages/data.table/index.html"). See [biokinetics](../reference/biokinetics.html) for all available arguments. In this vignette we use a dataset representing the Delta wave which is installed with this package, specifying a hierarchical model that just looks at the effect of infection history.
The `fit` method then has the same function signature as the underlying [cmdstanr::sample](https://mc-stan.org/cmdstanr/reference/model-method-sample.html) method. Here we specify a relatively small number of iterations of the algorithm to limit the time it takes to compile this vignette.
```{r, warning=FALSE, message=FALSE, results="hide"}
dat <- data.table::fread(system.file("delta_full.rds", package = "epikinetics"))
-mod <- epikinetics::scova$new(data = dat, covariate_formula = ~0 + infection_history)
+mod <- epikinetics::biokinetics$new(data = dat, covariate_formula = ~0 + infection_history)
delta <- mod$fit(parallel_chains = 4,
iter_warmup = 50,
iter_sampling = 200,
diff --git a/vignettes/data.Rmd b/vignettes/data.Rmd
index 6006154..af88f7f 100644
--- a/vignettes/data.Rmd
+++ b/vignettes/data.Rmd
@@ -39,17 +39,17 @@ After fitting a model, a [CmdStanMCMC](https://mc-stan.org/cmdstanr/reference/Cm
that users who are already familiar with `cmdstanr` are free to do what they want with the fitted model.
**Important!**
-**The data provided to `scova$new` is converted to a base2 log scale before inference is performed. This means that if working
+**The data provided to `biokinetics$new` is converted to a base2 log scale before inference is performed. This means that if working
directly with the fitted `CmdStanMCMC` all values will be on this scale. The package provides a helper function for converting
back to the original scale: [convert_log_scale_inverse](../reference/convert_log_scale_inverse.html).**
Three further functions provide model outputs that we think are particularly useful in [data.table](https://cran.r-project.org/web/packages/data.table/) format.
-[Scova](../reference/scova.html) contains documentation on each of these functions so please read that first; this Vignette provides
+[biokinetics](../reference/biokinetics.html) contains documentation on each of these functions so please read that first; this Vignette provides
guidance on the correct interpretation of each column in the returned tables. (In these functions data is returned on the original scale).
## simulate_population_trajectories
-See the documentation for this function [here](../reference/scova.html#method-simulate-population-trajectories).
+See the documentation for this function [here](../reference/biokinetics.html#method-simulate-population-trajectories).
There are 2 different output formats depending on whether the provided `summarise` argument is `TRUE` or `FALSE`.
* `summarise = TRUE`