documenting new kalis v2 functions

R/CalcTraces.R

@@ -1,25 +1,25 @@
-#' Title TODO
+#' Fast Calculation of Matrix Trace and Hilbert Schmidt Norm
 #'
-#' Short Description TODO
+#' Provides multithreaded calculation of trace and Hilbert Schmidt Norm of a matrix PMP (where P is a projection matrix) without explicitly forming PMP.
 #'
-#' Long Description TODO
+#' P here is assumed to have the form I-QQ' for some matrix Q of orthogonal columns
 #'
 #' @param M
-#'        TODO
+#'        a real symmetric R matrix
 #' @param tX
-#'        TODO
+#'        `t((Q %*% (J%*%Q)) - (M %*% Q))`
 #' @param tQ
-#'        TODO
+#'        `t(Q)`
 #' @param J
-#'        TODO
+#'        `crossprod(Q, M)`
 #' @param from_recipient
-#'        TODO
+#'        haplotype index at which to start trace calculation -- useful for distributed computation (experimental feature, more documentation to come 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
+#' a list containing three elements, the first is the trace `tr(PMP)`, the second is the *squared* Hilbert Schmidt Norm of PMP `tr((PMP)'PMP)`, the third is the diag of `PMP`.
 #'
 #' @examples
 #' # TODO

R/CladeMat.R

@@ -18,17 +18,17 @@
 #'        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
+#'        the change in distance that is expected to correspond to a single mutation (typically \eqn{-log(\mu)}) for the LS model)
 #' @param thresh
-#'        TODO
+#'        a regularization parameter: differences distances must exceed this threshold (in `unit.dist` units) in order to used in forming the local relatedness matrix. Defaults to `0.2`.
 #' @param max1var
-#'        TODO
+#'        a logical regularization parameter. When TRUE, differences in distances exceeding 1 `unit.dist` are set to 1 (so that any edge in the latent ancestral tree with multiple mutations on them are treated as if only one mutation was on it).
 #' @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.
+#' A list, the first element contains a list of tied nearest neighbors (one for each haplotype). Other elements return other information to allow for efficient removal of singletons and sprigs by [PruneCladeMat()].
 #'
 #' @examples
 #' # TODO

R/FB.R

@@ -6,7 +6,7 @@
 #' `Forward` implements the forward algorithm to advance the Li and Stephens rescaled hidden Markov model forward probabilities to a new target variant.
 #' Naturally, this can only propagate a table to variants downstream of its current position.
 #'
-#' For mathematical details please see Section 2 of the kalis paper (TODO: ref).
+#' For mathematical details please see Section 2 of the kalis paper (https://doi.org/10.1186/s12859-024-05688-8).
 #' Note that the precise formulation of the forward equation is determined by whether the flag `use.spiedel` is set in the parameters provided in `pars`.
 #'
 #' @param fwd a `kalisForwardTable` object, as returned by
@@ -111,7 +111,7 @@ Forward <- function(fwd,
 #' variant.
 #' Naturally, this can only propagate a table to variants upstream of its current position.
 #'
-#' For mathematical details please see Section 2 of the kalis paper (TODO: ref).
+#' For mathematical details please see Section 2 of the kalis paper (https://doi.org/10.1186/s12859-024-05688-8).
 #' Note that the precise formulation of the backward equation is determined by whether the flag `use.spiedel` is set in the parameters provided in `pars`.
 #'
 #' **Beta-theta space**