Revised docs

DESCRIPTION

@@ -8,7 +8,13 @@ Authors@R: c(
              email = "rich.fitzjohn@gmail.com"),
       person("Anne", "Cori", role = "aut"),
       person("Thibaut", "Jombart", role = "aut"))
-Description: Discrete approximations of continuous distributions.
+Description: Creates discretised versions of continuous 
+      distribution functions by mapping continuous values 
+      to an underlying discrete grid, based on a (uniform) 
+      frequency of discretisation, a valid discretisation 
+      point, and an integration range. For a review of 
+      discretisation methods, see 
+      Chakraborty (2015) <doi: https://doi.org/10.1186/s40488-015-0028-6>.
 License: MIT + file LICENSE
 LazyData: true
 URL: https://github.com/reconhub/distcrete
@@ -18,4 +24,4 @@ Suggests:
     rmarkdown,
     testthat
 RoxygenNote: 6.0.1
-VignetteBuilder: knitr
+VignetteBuilder: knitr

R/distcrete.R

@@ -1,29 +1,51 @@
-##' Discretise a distribution.
-##' @title Discretise a distribution
-##' @param name The name of a distribution function (e.g.,
-##'   \code{norm}, \code{gamma}).  The distribution must have a cdf
-##'   function (e.g., \code{pnorm}) and a quantile function (e.g.,
-##'   \code{qnorm}) defined.
-##'
-##' @param interval The interval to discretise the interval onto.
-##'
-##' @param ... Parameters to \code{cdf}.  Can be matched positionally
-##'   or by name.
-##'
-##' @param w How to weight the endpoints; must be between 0 and 1.  If
-##'   0.5 then integration happens centred around the interval, if 0
-##'   floor, if 1 then ceiling.
-##'
-##' @param anchor Any location that is a valid \code{x}
-##' @export
-##' @author Rich FitzJohn
-##' @examples 
-##' set.seed(415)
-##' d0 <- distcrete::distcrete("gamma", 1, shape = 3, w = 0)
-##' d0$d(1:10)
-##' d0$p(c(.1,.5))
-##' d0$q(c(.1,.5))
-##' d0$r(10)
+#' Discretise a distribution.
+#' @title Discretise a distribution
+#' @param name The name of a distribution function (e.g.,
+#'   \code{norm}, \code{gamma}).  The distribution must have a cdf
+#'   function (e.g., \code{pnorm}) and a quantile function (e.g.,
+#'   \code{qnorm}) defined.
+#'
+#' @param interval The interval to discretise the interval onto.
+#'
+#' @param ... Parameters to \code{cdf}.  Can be matched positionally
+#'   or by name.
+#'
+#' @param w How to weight the endpoints; must be between 0 and 1.  
+#'   If 0.5 then integration happens centred around the interval, if
+#'   0 floor, if 1 then ceiling.
+#'
+#' @param anchor Any location that is a valid \code{x}
+#' @export
+#' @author Rich FitzJohn
+#' @examples 
+#' set.seed(415)
+#' d0 <- distcrete::distcrete("gamma", 1, shape = 3, w = 0)
+#' d0$d(1:10)
+#' d0$p(c(.1,.5))
+#' d0$q(c(.1,.5))
+#' d0$r(10)
+#' 
+#' @details {
+#' \itemize{
+#'\item
+#'\eqn{x_{c}}: a random variable with a known continous distribution, with
+#'\eqn{f_{c}} its p.d.f and \eqn{F_{c}} the corresponding c.d.f.
+#'\item
+#'\eqn{x_{d}}: a random variable following a discrete distribution derived
+#'from \eqn{f_{c}}
+#'}
+#'
+#'The p.m.f. of \eqn{x_{d}} is defined for any discrete value \eqn{X} by: 
+#'  \deqn{
+#'    p(x_{d} = X) = p(x_{c} \in \left[X - (wi/2) ; X + (wi/2)\left[) = F_c(X + wi/2) - F_c(X - wi/2)
+#'   } where \eqn{i} is the width of the discretising interval, and \#'(w} is
+#'an offset describing how continuous values are mapped onto a discrete
+#'scale. For instance, with \eqn{i = 1} and \eqn{w = 0.5}, any values on
+#'\eqn{\left[2.5 ; 3.5\left[} are mapped to 2; for \eqn{i = 1} and \eqn{w = 0\
+#'), any values on \eqn{\left[1 ; 2\left[} is mapped to \eqn{1}.
+#'}
+
+
 distcrete <- function(name, interval, ..., w = 0.5, anchor = 0) {
   ## TODO: the offset / reverse parts should be done against the
   ## returned objects because they alter only the range?