Improve normalization documentation

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: TreeDist
 Type: Package
 Title: Calculate and Map Distances Between Phylogenetic Trees
-Version: 2.7.0.9001
+Version: 2.7.0.9002
 Authors@R: c(person("Martin R.", "Smith",
                     email = "[email protected]", 
                     role = c("aut", "cre", "cph", "prg"), 

NEWS.md

@@ -1,6 +1,8 @@
-# TreeDist 2.7.0.9001 (development)
+# TreeDist 2.7.0.9002 (development)
 
-- Fix dead links in documentation
+- Improve documentation of normalization.
+
+- Fix dead links in documentation.
 
 - Fix `KCDiameter.multiPhylo()` for multiple trees.
 

R/tree_distance_info.R

@@ -82,12 +82,16 @@
 #' for a compilation of expected values under different metrics for trees with
 #' up to 200 leaves.
 #' 
-#' Alternatively, to scale against the information content or entropy of all 
-#' splits in the most or least informative tree, use `normalize = `[`pmax`] or 
-#' [`pmin`] respectively.
+#' Alternatively, use `normalize = `[`pmax`] or [`pmin`] to scale against the
+#' information content or entropy of all splits in the most (`pmax`) or
+#' least (`pmin`) informative tree in each pair.
 #' To calculate the relative similarity against a reference tree that is known
 #' to be "correct", use `normalize = SplitwiseInfo(trueTree)` (SPI, MSI) or
 #' `ClusteringEntropy(trueTree)` (MCI).
+#' For worked examples, see the internal function [`NormalizeInfo()`], which is
+#' called from distance functions with the parameter `how = normalize`.
+#' .
+#' 
 #'
 #' # Distances between large trees
 #' 
@@ -171,7 +175,9 @@
 #' SharedPhylogeneticInfo(tree1, tree3) # = 0
 #' MutualClusteringInfo(tree1, tree3) # > 0
 #' 
-#' # Converting trees to Splits objects can speed up multiple comparisons
+#' # Distance functions internally convert trees to Splits objects.
+#' # Pre-conversion can reduce run time if the same trees will feature in
+#' # multiple comparisons
 #' splits1 <- TreeTools::as.Splits(tree1)
 #' splits2 <- TreeTools::as.Splits(tree2)
 #' 

R/tree_distance_utilities.R

@@ -409,6 +409,38 @@ CompareAll <- function(x, Func, FUN.VALUE = Func(x[[1]], x[[1]], ...),
 #' independently (optional)
 #' @param how Method for normalization
 #' @param \dots Additional parameters to `InfoInTree()` or `how`.
+#' @returns `NormalizeInfo()` returns an object corresponding to the normalized
+#' values of `unnormalized`.
+#' @examples
+#' library("TreeTools", quietly = TRUE)
+#' pair1 <- c(BalancedTree(9), StarTree(9))
+#' pair2 <- c(BalancedTree(9), PectinateTree(9))
+#' 
+#' # We'll let the number of nodes define the total information in a tree
+#' Nnode(pair1)
+#' Nnode(pair2)
+#' 
+#' # Let's normalize a unit distance
+#' rawDist <- cbind(c(1, 1), c(1, 1))
+#' 
+#' # With `Combine = "+"`, the maximum distance is the sum of
+#' # the information in each tree
+#' denominator <- outer(Nnode(pair1), Nnode(pair2), "+")
+#' 
+#' NormalizeInfo(rawDist, pair1, pair2, InfoInTree = ape::Nnode, Combine = "+")
+#' rawDist / denominator
+#' 
+#' 
+#' # A denominator can be specified manually using `how`:
+#' NormalizeInfo(rawDist, pair1, pair2, InfoInTree = ape::Nnode, how = 16)
+#' rawDist / 16
+#' 
+#' 
+#' # `how` also allows the denominator to be computed from trees:
+#' outer(Nnode(pair1), Nnode(pair2), pmin)
+#' NormalizeInfo(rawDist, pair1, pair2, InfoInTree = ape::Nnode, how = pmin)
+#' rawDist / outer(Nnode(pair1), Nnode(pair2), pmin)
+#' 
 #' @keywords internal
 #' @template MRS
 #' @importFrom TreeTools KeepTip TipLabels