Add explanation of weights for scan1 and est_herit (Issue rqtl#221)

NEWS.md

@@ -13,6 +13,9 @@
   that aren't two characters, and add an explanation of this in the
   help info. (Issue #220)
 
+- More fully explain the use of weights in `est_herit()` and
+  `scan1()`. (Issue #221)
+
 
 ## qtl2 0.32 (2023-04-21)
 

R/est_herit.R

@@ -26,6 +26,10 @@
 #' matrix \eqn{\sigma^2 [h^2 (2 K) + I]}{sigmasq*[hsq*2*K+I]} where
 #' \eqn{K} is the kinship matrix and \eqn{I} is the identity matrix.
 #'
+#' If `weights` are provided, the covariance matrix becomes
+#' \eqn{\sigma^2 [h^2 (2 K) + D]}{sigmasq*[hsq*2*K+D]} where
+#' \eqn{D} is a diagonal matrix with the reciprocal of the weights.
+#'
 #' For each of the inputs, the row names are used as
 #' individual identifiers, to align individuals.
 #'

R/scan1.R

@@ -61,6 +61,10 @@
 #' mean 0 and covariance matrix \eqn{\sigma^2 [h^2 (2 K) +
 #' I]}{sigmasq*[hsq*2*K+I]}, taking \eqn{h^2}{hsq} to be known.
 #'
+#' Note that if `weights` are provided, the covariance matrix becomes
+#' \eqn{\sigma^2 [h^2 (2 K) + D]}{sigmasq*[hsq*2*K+D]} where
+#' \eqn{D} is a diagonal matrix with the reciprocal of the weights.
+#'
 #' For each of the inputs, the row names are used as
 #' individual identifiers, to align individuals. The `genoprobs`
 #' object should have a component `"is_x_chr"` that indicates