From f0d3436b7df37cddd1193967644ede26cdd19f76 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9otime=20Pralas?=
 <151254073+thpralas@users.noreply.github.com>
Date: Tue, 16 Apr 2024 15:47:51 +0300
Subject: [PATCH] Explain difference between phylogenetic and hierarchy trees
 (#510)

---
 R/taxonomy.R          | 21 +++++++++++++--------
 man/hierarchy-tree.Rd | 21 +++++++++++++++++----
 2 files changed, 30 insertions(+), 12 deletions(-)

diff --git a/R/taxonomy.R b/R/taxonomy.R
index 97fc0e6ca..5dd3b3d73 100644
--- a/R/taxonomy.R
+++ b/R/taxonomy.R
@@ -127,7 +127,6 @@
 #' 
 #' # getTaxonomyRanks is to get/check if the taxonomic ranks is set to "TAXA1"
 #' getTaxonomyRanks()
-#' 
 NULL
 
 #' @rdname taxonomy-methods
@@ -414,16 +413,23 @@ setMethod("getTaxonomyLabels", signature = c(x = "SummarizedExperiment"),
 #' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{SummarizedExperiment}}
 #' object and add this hierarchy tree into the \code{rowTree}.
 #' 
-#' \code{addHierarchyTree} calculates hierarchy tree from the available taxonomic
-#'   information and add it to \code{rowTree}.
+#' @inheritParams taxonomy-methods
+#' 
+#' @details
+#' 
+#' \code{addHierarchyTree} calculates a hierarchy tree from the available 
+#'   taxonomic information and add it to \code{rowTree}.
 #'   
 #' \code{getHierarchyTree} generates a hierarchy tree from the available
 #'   taxonomic information. Internally it uses
 #'   \code{\link[TreeSummarizedExperiment:toTree]{toTree}} and
 #'   \code{\link[TreeSummarizedExperiment:resolveLoop]{resolveLoop}} to sanitize
 #'   data if needed.
-#' 
-#' @inheritParams taxonomy-methods
+#'   
+#' Please note that a hierarchy tree is not an actual phylogenetic tree.
+#' A phylogenetic tree represents evolutionary relationships among features.
+#' On the other hand, a hierarchy tree organizes species into a hierarchical 
+#' structure based on their taxonomic ranks. 
 #' 
 #' @return
 #' \itemize{
@@ -437,16 +443,15 @@ setMethod("getTaxonomyLabels", signature = c(x = "SummarizedExperiment"),
 #' @name hierarchy-tree
 #' 
 #' @examples
-#' # Generating a hierarchy tree based on available taxonomic information.
+#' # Generate a tree based on taxonomic rank hierarchy (a hierarchy tree).
 #' data(GlobalPatterns)
 #' tse <- GlobalPatterns
 #' getHierarchyTree(tse)
 #' 
-#' # Adding a hierarchy tree based on the available taxonomic information. 
+#' # Add a hierarchy tree to a TreeSummarizedExperiment.
 #' # Please note that any tree already stored in rowTree() will be overwritten.
 #' tse <- addHierarchyTree(tse)
 #' tse
-#' 
 NULL
 
 #' @rdname hierarchy-tree
diff --git a/man/hierarchy-tree.Rd b/man/hierarchy-tree.Rd
index 3f46234a2..bcfc1069c 100644
--- a/man/hierarchy-tree.Rd
+++ b/man/hierarchy-tree.Rd
@@ -38,24 +38,37 @@ These functions generate a hierarchy tree using taxonomic information from a
 object and add this hierarchy tree into the \code{rowTree}.
 }
 \details{
-\code{addHierarchyTree} calculates hierarchy tree from the available taxonomic
-information and add it to \code{rowTree}.
+\code{addHierarchyTree} calculates a hierarchy tree from the available
+taxonomic information and add it to \code{rowTree}.
 
 \code{getHierarchyTree} generates a hierarchy tree from the available
 taxonomic information. Internally it uses
 \code{\link[TreeSummarizedExperiment:toTree]{toTree}} and
 \code{\link[TreeSummarizedExperiment:resolveLoop]{resolveLoop}} to sanitize
 data if needed.
+
+Please note that a hierarchy tree is not an actual phylogenetic tree.
+A phylogenetic tree represents evolutionary relationships among features.
+On the other hand, a hierarchy tree organizes species into a hierarchical
+structure based on their taxonomic ranks.
 }
 \examples{
-# Generating a hierarchy tree based on available taxonomic information.
+# Generate a tree based on taxonomic rank hierarchy (a hierarchy tree).
 data(GlobalPatterns)
 tse <- GlobalPatterns
 getHierarchyTree(tse)
 
-# Adding a hierarchy tree based on the available taxonomic information. 
+# Add a hierarchy tree to a TreeSummarizedExperiment.
 # Please note that any tree already stored in rowTree() will be overwritten.
 tse <- addHierarchyTree(tse)
 tse
 
+# For instance, the TreeSummarizedExperiment Tengeler2020 contains an
+# actual phylogenetic tree.
+
+data(Tengeler2020)
+tse2 <- Tengeler2020
+phylo_tree <- rowTree(tse2)
+phylo_tree
+
 }