biokinetics.RdCreate an instance of the biomarker kinetics model and fit it to a dataset.
new()Initialise the kinetics model.
biokinetics$new(
priors = biokinetics_priors(),
data = NULL,
file_path = NULL,
covariate_formula = ~0,
preds_sd = 0.25,
scale = "natural",
upper_censoring_limit = NULL,
lower_censoring_limit = NULL,
strict_upper_limit = TRUE,
strict_lower_limit = TRUE
)priorsObject of type biokinetics_priors. Default biokinetics_priors().
dataOptional data table of model inputs. One of data or file must be provided. See the data vignette
for required columns: vignette("data", package = "epikinetics").
file_pathOptional file path to model inputs in CSV format. One of data or file must be provided.
covariate_formulaFormula specifying linear regression model. Note all variables in the formula will be treated as categorical variables. Default ~0.
preds_sdStandard deviation of predictor coefficients. Default 0.25.
scaleOne of "log" or "natural". Default "natural". Is provided data on a log or a natural scale? If on a natural scale it will be converted to a log scale for model fitting.
upper_censoring_limitOptional value at which to upper censor data points. This is needed to construct a likelihood for upper censored values, so only needs to be provided if you have such values in the dataset. If not provided, no censoring will be done.
lower_censoring_limitOptional value at which to lower censor data points. This is needed to construct a likelihood for lower censored values, so only needs to be provided if you have such values in the dataset. If not provided, no censoring will be done.
strict_upper_limitLogical. Whether values greater than the upper censoring limit should be censored. If FALSE, only values exactly equal to the upper censoring limit will be censored. Default TRUE.
strict_lower_limitLogical. Whether values smaller than the lower censoring limit should be censored. If FALSE, only values exactly equal to the lower censoring limit will be censored. Default TRUE.
plot_prior_predictive()Plot the kinetics trajectory predicted by the model priors. Note that this is on a log scale, regardless of whether the data was provided on a log or a natural scale.
plot_model_inputs()Plot model input data with a smoothing function. Note that this plot is of the data as provided to the Stan model so is on a log scale, regardless of whether data was provided on a log or a natural scale.
get_covariate_lookup_table()View the mapping of human readable covariate names to the model variable p.
fit()Fit the model and return CmdStanMCMC fitted model object.
...Named arguments to the sample() method of CmdStan model.
objects: https://mc-stan.org/cmdstanr/reference/model-method-sample.html
A CmdStanMCMC fitted model object: https://mc-stan.org/cmdstanr/reference/CmdStanMCMC.html
extract_individual_parameters()Extract fitted individual parameters
biokinetics$extract_individual_parameters(
n_draws = 2000,
include_variation_params = TRUE,
human_readable_covariates = TRUE
)simulate_population_trajectories()Process the model results into a data table of titre values over time.
t_maxInteger. Maximum number of time points to include.
summariseBoolean. Default TRUE. If TRUE, summarises over draws from posterior parameter distributions to return 0.025, 0.5 and 0.975 quantiles, labelled lo, me and hi, respectively. If FALSE returns values for individual draws from posterior parameter distributions.
n_drawsInteger. Maximum number of samples to include. Default 2000.
A data.table containing titre values at time points. If summarise = TRUE, columns are time_since_last_exp,
me, lo, hi, titre_type, and a column for each covariate in the hierarchical model. If summarise = FALSE, columns are
time_since_last_exp, .draw, t0_pop, tp_pop, ts_pop, m1_pop, m2_pop, m3_pop, beta_t0, beta_tp, beta_ts, beta_m1, beta_m2, beta_m3, mu
titre_type and a column for each covariate in the hierarchical model. See the data vignette for details:
vignette("data", package = "epikinetics")
population_stationary_points()Process the stan model results into a data.table.
A data.table of peak and set titre values. Columns are tire_type, mu_p, mu_s, rel_drop_me, mu_p_me,
mu_s_me, and a column for each covariate. See the data vignette for details:
vignette("data", package = "epikinetics")
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.
biokinetics$simulate_individual_trajectories(
summarise = TRUE,
n_draws = 2000,
time_shift = 0
)summariseBoolean. If TRUE, average the individual trajectories to get lo, me and hi values for the population, disaggregated by titre type. If FALSE return the indidivudal trajectories. Default TRUE.
n_drawsInteger. Maximum number of samples to draw. Default 2000.
time_shiftInteger. Number of days to adjust the exposure day by. Default 0.
A data.table. If summarise = TRUE columns are calendar_day, titre_type, me, lo, hi, time_shift.
If summarise = FALSE, columns are pid, draw, time_since_last_exp, mu, titre_type, exposure_day, calendar_day, time_shift
and a column for each covariate in the regression model. See the data vignette for details:
vignette("data", package = "epikinetics").