Commit 85294add authored by Poppy Miller's avatar Poppy Miller
Browse files

Added more documentation

parent 25bfb74e
......@@ -22,7 +22,7 @@
#' This function fits a non-parametric Poisson source attribution model for human cases of
#' disease. It supports multiple types, sources, times and locations. The number of
#' human cases for each type, time and location follow a Poisson likelihood.
#' \deqn{y_{itl}\sim\textsf{Poisson}(\lambda_{itl})}
#'
#' @section Methods:
#' \describe{
#' \item{\code{new(data, k, priors, a_q, inits = NULL)}}{Constructor takes
......@@ -146,8 +146,8 @@
#'
#' \item{\code{print_priors}}{returns a list containing the DP concentration
#' parameter \code{a_q}, and the priors (R6 class with members named \code{a_alpha}
#' (members are array \code{a_alpha[sources, times, locations]}), \code{a_r} (an array \code{a_r[types, sources, times]}),
#' \code{a_theta} and \code{b_theta}).}
#' (members are array \code{a_alpha[sources, times, locations]}), \code{a_r} (an array
#' \code{a_r[types, sources, times]}), \code{a_theta} and \code{b_theta}).}
#'
#' \item{\code{print_inits}}{returns an R6 class holding the initial values
#' (members are \code{alpha} (an array \code{alpha[sources, times, locations]}),
......@@ -170,7 +170,8 @@
#' If \code{flatten} is set to \code{TRUE}, it returns a dataframe with 1 column per
#' parameter, otherwise it returns a list containing \code{params} containing a
#' subset of the following arrays: \code{alpha[Sources, Times, Locations, iters]}, \code{q[Types, iters]},
#' \code{s[Types, iters]}, \code{r[Types, Sources, Times, iters]}, \code{lambda_i[Types, Times, Locations, iters]},
#' \code{s[Types, iters]}, \code{r[Types, Sources, Times, iters]},
#' \code{lambda_i[Types, Times, Locations, iters]},
#' \code{lambda_j[Sources, Times, Locations, iters]}.
#'
#' \code{drop}
......@@ -186,11 +187,12 @@
#' are \code{"percentiles"} and \code{"spin"}).
#' See \code{extract} for details on the subsetting. \code{lambda_j_prop} returns the
#' proportion of cases attributed to each source \code{j} and is calculated by dividing
#' each iteration of \code{lambda_{jtl}} values by their sum within each time \code{t} and location \code{l}.}
#' each iteration of \code{lambda_{jtl}} values by their sum within each time \code{t}
#' and location \code{l}.}
#'
#' \item{\code{plot_heatmap(iters, cols = c("blue","white"), hclust_method = "complete")}}{
#' Creates a dendrogram and heatmap for the type effect groupings (\code{s} parameter in the model).
#' This uses the heatmap.2 function from gplots.
#' Creates a dendrogram and heatmap for the type effect groupings (\code{s} parameter
#' in the model). This uses the heatmap.2 function from gplots.
#'
#' \code{iters} is a vector containing the iterations to be used in constructing
#' the graph. Default is all iterations in posterior.
......@@ -203,6 +205,31 @@
#' between the two chosen colours. See ?colorRampPalette for more details..}
#' }
#'
#' @section Details:
#' \describe{
#' This function fits a source attribution model for human cases of disease.
#' It supports multiple types, sources, times and locations. The number of human cases
#' for each type, time and location follows a Poisson or Negative Binomial likelihood.
#' \emph{Model}
#' \deqn{y_{itl}\sim\textsf{Poisson}(\lambda_{itl})}
#' where
#' \deqn{\lambda_{itl}=\sum_{j=1}^{m}\lambda_{ijtl}=q_{k(i)}\sum_{j=1}^{m}(r_{ijt}\cdot k_{j}\cdot alpha_{jtl})}
#'
#' The parameters are defined as follows:
#' \deqn{a_{jtl}} is the unknown source effect for source \eqn{j}, time \eqn{t}, location \eqn{l}
#' \deqn{q_{k(i)}} is the unknown type effect for type \eqn{i} in group \eqn{k}.
#' \deqn{x_{ij}} is the known number of positive samples for each source \eqn{j} type\eqn{i} combination
#' \deqn{n_{ij}} is the known total number of samples for each source \eqn{j} type \eqn{i} combination
#' \deqn{k_{j}} is the fixed prevalence in source (i.e. the number of positive samples
#' divided by the number of negative samples) \eqn{j}
#' \deqn{r_{ijt}} is the unknown relative occurrence of type \eqn{i} on source \eqn{j}.
#'
#' \emph{Priors}
#' \deqn{r_{.jt}\sim Dirichlet(a_r_{1jt},..., a_r_{njt})}
#' \deqn{a_{tl}\sim Dirichlet(a_alpha_{1tl},..., a_alpha_{mtl})}
#' \deqn{q\sim DP(alpha, Gamma(a_{theta},b_{theta}))}
#' }
#'
#' @references Chen, M.-H. and Shao, Q.-M. (1998). Monte Carlo estimation of Bayesian credible and HPD intervals, \emph{Journal of Computational and Graphical Statistics}, 7.
#' @references Liu Y, Gelman A, Zheng T (2015). "Simulation-efficient shortest probability intervals." Statistics and Computing.
#' @author Chris Jewell and Poppy Miller \email{p.miller at lancaster.ac.uk}
......
......@@ -4,12 +4,14 @@
\name{HaldDP}
\alias{HaldDP}
\title{Runs the HaldDP source attribution model}
\format{Object of \code{\link{R6Class}} with methods for creating a HaldDP model, running the model, and accessing and plotting the results.}
\format{Object of \code{\link{R6Class}} with methods for creating a HaldDP model,
running the model, and accessing and plotting the results.}
\usage{
HaldDP
}
\value{
Object of \code{\link{HaldDP}} with methods for creating a HaldDP model, running the model, and accessing and plotting the results.
Object of \code{\link{HaldDP}} with methods for creating a HaldDP model,
running the model, and accessing and plotting the results.
}
\description{
Runs the HaldDP source attribution model
......@@ -19,7 +21,6 @@ Runs the HaldDP source attribution model
This function fits a non-parametric Poisson source attribution model for human cases of
disease. It supports multiple types, sources, times and locations. The number of
human cases for each type, time and location follow a Poisson likelihood.
\deqn{y_{itl}\sim\textsf{Poisson}(\lambda_{itl})}
}
\section{Methods}{
......@@ -124,7 +125,7 @@ human cases for each type, time and location follow a Poisson likelihood.
are appended to any previous iterations, or overwrites them. When
\code{append = TRUE}, the starting values are the last iteration and no
\code{burn_in} is removed. Running the model for the first time, or changing any
model or fitting parameters will set \code{append = FALSE}.}
model or fitting parameters will set \code{append = FALSE}. }
\item{\code{print_data}}{returns a list containing the human data \code{y}
(an array y[types, times, locations]), the source data \code{X} (an array X[types, sources, times]),
......@@ -134,8 +135,8 @@ human cases for each type, time and location follow a Poisson likelihood.
\item{\code{print_priors}}{returns a list containing the DP concentration
parameter \code{a_q}, and the priors (R6 class with members named \code{a_alpha}
(members are array \code{a_alpha[sources, times, locations]}), \code{a_r} (an array \code{a_r[types, sources, times]}),
\code{a_theta} and \code{b_theta}).}
(members are array \code{a_alpha[sources, times, locations]}), \code{a_r} (an array
\code{a_r[types, sources, times]}), \code{a_theta} and \code{b_theta}).}
\item{\code{print_inits}}{returns an R6 class holding the initial values
(members are \code{alpha} (an array \code{alpha[sources, times, locations]}),
......@@ -158,7 +159,8 @@ human cases for each type, time and location follow a Poisson likelihood.
If \code{flatten} is set to \code{TRUE}, it returns a dataframe with 1 column per
parameter, otherwise it returns a list containing \code{params} containing a
subset of the following arrays: \code{alpha[Sources, Times, Locations, iters]}, \code{q[Types, iters]},
\code{s[Types, iters]}, \code{r[Types, Sources, Times, iters]}, \code{lambda_i[Types, Times, Locations, iters]},
\code{s[Types, iters]}, \code{r[Types, Sources, Times, iters]},
\code{lambda_i[Types, Times, Locations, iters]},
\code{lambda_j[Sources, Times, Locations, iters]}.
\code{drop}
......@@ -174,11 +176,12 @@ human cases for each type, time and location follow a Poisson likelihood.
are \code{"percentiles"} and \code{"spin"}).
See \code{extract} for details on the subsetting. \code{lambda_j_prop} returns the
proportion of cases attributed to each source \code{j} and is calculated by dividing
each iteration of \code{lambda_{jtl}} values by their sum within each time \code{t} and location \code{l}.}
each iteration of \code{lambda_{jtl}} values by their sum within each time \code{t}
and location \code{l}.}
\item{\code{plot_heatmap(iters, cols = c("blue","white"), hclust_method = "complete")}}{
Creates a dendrogram and heatmap for the type effect groupings (\code{s} parameter in the model).
This uses the heatmap.2 function from gplots.
Creates a dendrogram and heatmap for the type effect groupings (\code{s} parameter
in the model). This uses the heatmap.2 function from gplots.
\code{iters} is a vector containing the iterations to be used in constructing
the graph. Default is all iterations in posterior.
......@@ -191,6 +194,33 @@ human cases for each type, time and location follow a Poisson likelihood.
between the two chosen colours. See ?colorRampPalette for more details..}
}
}
\section{Details}{
\describe{
This function fits a source attribution model for human cases of disease.
It supports multiple types, sources, times and locations. The number of human cases
for each type, time and location follows a Poisson or Negative Binomial likelihood.
\emph{Model}
\deqn{y_{itl}\sim\textsf{Poisson}(\lambda_{itl})}
where
\deqn{\lambda_{itl}=\sum_{j=1}^{m}\lambda_{ijtl}=q_{k(i)}\sum_{j=1}^{m}(r_{ijt}\cdot k_{j}\cdot alpha_{jtl})}
The parameters are defined as follows:
\deqn{a_{jtl}} is the unknown source effect for source \eqn{j}, time \eqn{t}, location \eqn{l}
\deqn{q_{k(i)}} is the unknown type effect for type \eqn{i} in group \eqn{k}.
\deqn{x_{ij}} is the known number of positive samples for each source \eqn{j} type\eqn{i} combination
\deqn{n_{ij}} is the known total number of samples for each source \eqn{j} type \eqn{i} combination
\deqn{k_{j}} is the fixed prevalence in source (i.e. the number of positive samples
divided by the number of negative samples) \eqn{j}
\deqn{r_{ijt}} is the unknown relative occurrence of type \eqn{i} on source \eqn{j}.
\emph{Priors}
\deqn{r_{.jt}\sim Dirichlet(a_r_{1jt},..., a_r_{njt})}
\deqn{a_{tl}\sim Dirichlet(a_alpha_{1tl},..., a_alpha_{mtl})}
\deqn{q\sim DP(alpha, Gamma(a_{theta},b_{theta}))}
}
}
\examples{
data(campy)
zero_rows <- which(apply(campy[,c(2:7)], 1, sum) == 0)
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment