First batch of documentation fixes, some TODO items remain in these.

R/CladeMat.R

@@ -1,7 +1,42 @@
-#' Fast Clade Matrix Construction
+#' Fast clade matrix construction
+#'
+#' Constructs a clade matrix using forward and backward tables.
+#' The clade matrix captures genetic relatedness information in the distances from the Li & Stephens model that are not captured in the called clades.
+#'
+#' `CladeMat()` uses the forward and backward tables to construct the corresponding clade matrix which can then be tested, for example using a standard quadratic form score statistic.
+#'
+#' @references
+#' Christ, R., Wang, X., Aslett, L.J.M., Steinsaltz, D. and Hall, I. (2024) "Clade Distillation for Genome-wide Association Studies." bioRxiv 2024.09.30.615852. Available at: \doi{10.1101/2024.09.30.615852}.
+#'
+#' @param fwd
+#'        a `kalisForwardTable` object, as returned by [MakeForwardTable()] and propagated to a target variant by [Forward()].
+#'        This table must be at the same variant location as argument `bck`.
+#' @param bck
+#'        a `kalisBackwardTable` object, as returned by [MakeBackwardTable()] and propagated to a target variant by [Backward()].
+#'        This table must be at the same variant location as argument `fwd`.
+#' @param M
+#'        a matrix with half the number of rows and columns as the corresponding forward/backward tables.
+#'        This matrix is overwritten in place with the clade matrix result for performance reasons.
+#' @param unit.dist
+#'        TODO
+#' @param thresh
+#'        TODO
+#' @param max1var
+#'        TODO
+#' @param nthreads
+#'        the number of CPU cores to use.
+#'        By default uses the `parallel` package to detect the number of physical cores.
+#'
+#' @return
+#' TODO: this returns from C the list containing neighbourhood, similarity and total clades info, but need full details and list structure.
+#'
+#' @examples
+#' # TODO
+#'
+#'
 #' @export CladeMat
 CladeMat <- function(fwd, bck, M, unit.dist, thresh = 0.2, max1var = FALSE,
-                    nthreads = min(parallel::detectCores(logical = FALSE), fwd$to_recipient-fwd$from_recipient+1)){
+                     nthreads = min(parallel::detectCores(logical = FALSE), fwd$to_recipient-fwd$from_recipient+1)){
 
   # input checks
   #########################

R/Clades.R

@@ -199,14 +199,38 @@ PruneCladeMat <- function(M, neigh, sprigs, prune = "singleton.info", from.recip
 #' Probabilistic Clades
 #'
 #' Utility for calling probabilistic clades at, in between, or excluding variants.
-#' @param fwd a forward table as returned by [MakeForwardTable()]
-#' @param bck a backward table as returned by [MakeBackwardTable()]
-#' @param pars a `kalisParameters` object, as returned by [Parameters()].
-#' @param beta.theta.opts a list; see Details for [DistMat()].
-#' @param safety.checks a logical, should safety checks be applied to the distances?  See [DistMat()].
-#' @param neighbors a logical, should nearest neighbors be pre-calculated?  See [Neighbors()].
-#' @param use.forking a logical, should forked processes be used?
-#' @param nthreads the number of CPU cores to use. Currently, no parallelism is used.
+#'
+#' TODO longer description
+#'
+#' @references
+#' Christ, R., Wang, X., Aslett, L.J.M., Steinsaltz, D. and Hall, I. (2024) "Clade Distillation for Genome-wide Association Studies." bioRxiv 2024.09.30.615852. Available at: \doi{10.1101/2024.09.30.615852}.
+#'
+#' @param fwd
+#'        a `kalisForwardTable` object, as returned by [MakeForwardTable()] and propagated to a target variant by [Forward()].
+#'        This table must be at the same variant location as argument `bck`.
+#' @param bck
+#'        a `kalisBackwardTable` object, as returned by [MakeBackwardTable()] and propagated to a target variant by [Backward()].
+#'        This table must be at the same variant location as argument `fwd`.
+#' @param pars
+#'        a `kalisParameters` object, as returned by [Parameters()].
+#' @param beta.theta.opts
+#'        a list; see Details in [DistMat()] documentation page.
+#' @param safety.checks
+#'        a logical, should safety checks be applied to the distances?
+#'        See [DistMat()].
+#' @param neighbors
+#'        a logical, should nearest neighbors be pre-calculated?
+#'        See [Neighbors()].
+#' @param use.forking
+#'        a logical, should forked processes be used?
+#' @param forking.chunk.size
+#'        TODO
+#' @param mc.preschedule
+#'        TODO
+#' @param nthreads
+#'        the number of CPU cores to use.
+#'        By default no parallelism is used.
+#'
 #' @return
 #'   a `kalisClades` object encoding probabilistic clade calls
 #'

R/TableCache.R

@@ -16,16 +16,27 @@
 #' To use the cache, then instead of using the [Forward()] function,
 #' use [ForwardUsingTableCache()].
 #'
-#' @param pars a `kalisParameters` object, as returned by [Parameters()].
-#' @param size the maximum amount of RAM (in GB) to devote to this cache.
-#' @param from_recipient first recipient haplotype if creating a partial forward
-#'   table cache.  By default includes from the first recipient haplotype.
-#' @param to_recipient last recipient haplotype if creating a partial forward
-#'   table cache.  By default includes to the last recipient haplotype.
+#' @references
+#' Christ, R., Wang, X., Aslett, L.J.M., Steinsaltz, D. and Hall, I. (2024) "Clade Distillation for Genome-wide Association Studies." bioRxiv 2024.09.30.615852. Available at: \doi{10.1101/2024.09.30.615852}.
+#'
+#' @param pars
+#'        a `kalisParameters` object, as returned by [Parameters()].
+#' @param size
+#'        the maximum amount of RAM (in GB) to devote to this cache.
+#'        By default, 1GB.
+#' @param from_recipient
+#'        first recipient haplotype if creating a partial forward table cache.
+#'        By default includes from the first recipient haplotype.
+#' @param to_recipient
+#'        last recipient haplotype if creating a partial forward table cache.
+#'        By default includes to the last recipient haplotype.
+#' @param max.tables
+#'        positive integer indicating the maximum number of tables to use in the cache.
+#'        Both this and `size` will be honoured, so the number of tables may be smaller than this.
+#'        By default, equals \eqn{\lfloor\log_2(L)\rfloor}.
 #'
 #' @return
-#'   A list of forward tables representing a cache and ready to be filled is
-#'   returned.
+#'   A list of forward tables representing a cache and ready to be filled is returned.
 #'
 #' @seealso
 #'   [MakeForwardTable()] to make a forward table;
@@ -128,18 +139,13 @@ CreateForwardTableCache <- function(pars, size = 1, from_recipient = 1, to_recip
 #' To use the cache, then instead of using the [Forward()] function,
 #' use [ForwardUsingTableCache()].
 #'
-#' @param cache a cache of forward tables as generated by
-#'   [CreateForwardTableCache()]
-#' @param pars a `kalisParameters` object, as returned by [Parameters()].
-#' @param from the first locus which the geometrically spaced cache should be
-#'   built from.
-#'   By default the whole sequence length will be cached so this defaults to 1.
-#' @param to the last locus up to which the geometrically spaced cache should be
-#'   built.
-#'   By default the whole sequence length will be cached so this defaults to
-#'   `Inf`.
-#' @param nthreads the number of CPU cores to use.
-#'   By default no parallelism is used.
+#' @param cache
+#'        a cache of forward tables as generated by [CreateForwardTableCache()].
+#' @param pars
+#'        a `kalisParameters` object, as returned by [Parameters()].
+#' @param nthreads
+#'        the number of CPU cores to use.
+#'        By default uses the `parallel` package to detect the number of physical cores.
 #'
 #' @return
 #' There is nothing returned.