fit_baclava {baclava}R Documentation

Bayesian Analysis of Cancer Latency with Auxiliary Variable Augmentation

Description

Markov chain Monte Carlo sampler to fit a three-state mixture compartmental model of cancer natural history to individual-level screening and cancer diagnosis histories in a Bayesian framework.

Usage

fit_baclava(
  data.assess,
  data.clinical,
  baclava.object = NULL,
  M = 100L,
  thin = 1L,
  t0 = 0,
  theta_0 = list(),
  prior = list(),
  epsilon_rate_H = 0.001,
  epsilon_rate_P = 0.001,
  epsilon_psi = 0.001,
  indolent = TRUE,
  adaptive = NULL,
  round.age.entry = TRUE,
  verbose = TRUE,
  save.latent = FALSE
)

## S3 method for class 'baclava'
summary(object, ...)

## S3 method for class 'baclava'
print(x, ...)

Arguments

data.assess

A data.frame. Disease status assessments recorded during healthy or preclinical compartment, e.g., screenings for disease. The data must be structured as

  • id: A character, numeric, or integer object. The unique participant id to which the record pertains. Multiple records for each id are allowed.

  • age_assess: A numeric object. The participant's age at time of assessment.

  • disease_detected: An integer object. Must be binary 0/1, where 1 indicates that disease was detected at the assessment; 0 otherwise.

If the sensitivity parameter (beta) is screen-specific, an additional column screen_type is required indicating the type of each screen.

data.clinical

A data.frame. The clinical data. The data must be structured as

  • id: A character, numeric, or integer object. The unique participant id to which the record pertains. Note these must include those provided in data.assess. Must be only 1 record for each participant.

  • age_entry: A numeric object. The age at time of entry into the study. Note that this data is used to calculate a normalization; to expedite numerical integration, it is recommended that the ages be rounded. Optional input round.age.entry can be set to FALSE if this approximation is not desired; however, the computation time will significantly increase.

  • endpoint_type: A character object. Must be one of {"clinical", "censored", "preclinical"}. Type "clinical" indicates that disease was diagnosed in the clinical compartment (i.e., symptomatic). Type "preclinical" indicates that disease was diagnosed in the preclinical compartment (i.e., during an assessment). Type "censored" indicates disease was not diagnosed prior to end of study.

  • age_endpoint: A numeric object. The participant's age at the time the endpoint was evaluated.

If the sensitivity parameter (beta) is arm-specific, an additional column arm is required indicating the study arm to which each participant is assigned. Similarly, if the preclinical Weibull distribution is group-specific, an additional column grp.rateP is required. See Details for further information.

baclava.object

NULL or a 'baclava' object. To continue a calculation, provide the object returned by a previous call.

M

A positive integer object. The number of Monte Carlo samples. This is the total, i.e., M = adaptive$warmup + n_MCMC.

thin

A positive integer object. Keep each thin-th step of the sampler after the warmup period, if any, is complete.

t0

A non-negative scalar numeric object. The risk onset age. Must be less than the earliest assessment age, entry age, and endpoint age. If baclava.object is a 'baclava' object, this input is ignored.

theta_0

A list object. The initial values for all distribution parameters. If baclava.object is a 'baclava' object, this input is ignored. See Details for further information.

prior

A list object. The prior parameters. If baclava.object is a 'baclava' object, this input is ignored. See Details for further information.

epsilon_rate_H

A small scalar numeric. The Monte Carlo step size for rate_H (the rate parameter of the Weibull of the healthy compartment). If baclava.object is a 'baclava' object, this input is ignored.

epsilon_rate_P

A small scalar numeric or named numeric vector. The Monte Carlo step size for rate_P (the rate parameter of the Weibull of the preclinical compartment). If group-specific Weibull distributions are used, this must be a vector; see Details for further information. If baclava.object is a 'baclava' object, this input is ignored.

epsilon_psi

A small scalar numeric. The Monte Carlo step size for parameter psi (the probability of indolence). If disease under analysis does not have an indolent state, set to 0 and ensure that the initial value for psi in theta_0 is also 0. If baclava.object is a 'baclava' object, this input is ignored.

indolent

A logical object. If FALSE, disease under analysis does not have an indolent state, i.e., it is always progressive. This input is provided for convenience; if FALSE, epislon_psi and theta_0$psi will be set to 0. If baclava.object is a 'baclava' object, this input is ignored.

adaptive

NULL or named list. If NULL, the step sizes are not modified in the MCMC. If a list, the parameters for the adaptive MCMC. The provided list must contain elements "delta", the target acceptance rate; "warmup", the number of iterations to apply step size correction; and parameters "m0", "kappa", and "gamma". See Details for further information. If baclava.object is a 'baclava' object, this input is ignored.

round.age.entry

A logical object. If TRUE, the age at time of entry will be rounded to the nearest integer prior to performing the MCMC. This data is used to estimate the probability of experiencing clinical disease prior to entering the study, which is estimated using a time consuming numerical integration procedure. It is expected that rounding the ages at time of entry introduces minimal bias. If FALSE, and ages cannot be grouped, these integrals significantly increase computation time. If baclava.object is a 'baclava' object, this input is ignored.

verbose

A logical object. If TRUE, a progress bar will be shown during the MCMC.

save.latent

A logical object. If TRUE, latent variable tau_HP and indolence will be returned. These can be very large matrices. To estimate the cohort overdiagnosis probability using cohortODX(), this must be set to TRUE.

object

An object of class baclava.

...

Ignored.

x

An object of class baclava.

Details

Input theta_0 contains the initial values for all distribution parameters. The list must include

Input prior contains all distribution parameters for the priors. The list must include

It is possible to assign participants to study arms such that each arm has its own screening sensitivities and/or rate_P distributions, or to assign screen-type specific sensitivities.

To designate study arms, each of which will have its own screening sensitivities:

Similarly, if using multiple preclinical Weibull distributions (distributions will have the same shape_P),

To assign screen-specific sensitivities,

NOTE: If using integers to indicate group membership, vector names still must be provided. For example, if group membership is binary 0/1, vector elements of the prior, initial theta, and step size must be named as "0" and "1".

The adaptive MCMC tuning expression at step m + 1 is defined as

\epsilon_{m+1} = (1 - m^{\kappa}) \epsilon_{m} + m^{\kappa} \xi_{m+1},

where

\xi_{m+1} = \frac{\sqrt{m}}{\gamma}\frac{1}{m+m_0} \sum_{i=1}^{m} (\alpha_m - \delta).

To initiate the adaptive selection procedure, input adaptive must specify the parameters of the above expressions. Specifically, the provided list must contain elements "delta", the target acceptance rate; "warmup", the number of iterations to apply step size correction; and parameters "m0", "kappa", and "gamma".

Value

An object of S3 class baclava, which extends a list object.

Functions

Examples


data(screen_data)

theta_0 <- list("rate_H" = 7e-4, "shape_H" = 2.0,
                "rate_P" = 0.5  , "shape_P" = 1.0,
                "beta" = 0.9, psi = 0.4)
prior <- list("rate_H" = 0.01, "shape_H" = 1,
              "rate_P" = 0.01, "shape_P" = 1,
              "a_psi" = 1/2 , "b_psi" = 1/2,
              "a_beta" = 38.5, "b_beta" = 5.8)

# This is for illustration only -- the number of Gibbs samples should be
# significantly larger and the epsilon values should be tuned.
example <- fit_baclava(data.assess = data.screen,
                       data.clinical = data.clinical,
                       t0 = 30.0,
                       theta_0 = theta_0,
                       prior = prior)

summary(example)
print(example)

# To continue this calculation
example_continued <- fit_baclava(data.assess = data.screen,
                                 data.clinical = data.clinical,
                                 baclava.object = example)

[Package baclava version 1.1 Index]