Add documentation and README

Author: SamT123

.Rbuildignore

@@ -1,3 +1,4 @@
 ^mutationtree\.Rproj$
 ^\.Rproj\.user$
 ^LICENSE\.md$
+^\.github$

.github/.gitignore

@@ -0,0 +1 @@
+*.html

.github/workflows/R-CMD-check.yaml

@@ -0,0 +1,51 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+name: R-CMD-check.yaml
+
+permissions: read-all
+
+jobs:
+  R-CMD-check:
+    runs-on: ${{ matrix.config.os }}
+
+    name: ${{ matrix.config.os }} (${{ matrix.config.r }})
+
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - {os: macos-latest,   r: 'release'}
+          - {os: windows-latest, r: 'release'}
+          - {os: ubuntu-latest,   r: 'devel', http-user-agent: 'release'}
+          - {os: ubuntu-latest,   r: 'release'}
+          - {os: ubuntu-latest,   r: 'oldrel-1'}
+
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      R_KEEP_PKG_SOURCE: yes
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: ${{ matrix.config.r }}
+          http-user-agent: ${{ matrix.config.http-user-agent }}
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::rcmdcheck
+          needs: check
+
+      - uses: r-lib/actions/check-r-package@v2
+        with:
+          upload-snapshots: true
+          build_args: 'c("--no-manual","--compact-vignettes=gs+qpdf")'

DESCRIPTION

@@ -8,7 +8,7 @@ License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
-Imports: 
+Imports:
     ape,
     dplyr,
     fs,
@@ -17,6 +17,7 @@ Imports:
     labbook,
     magrittr,
     purrr,
+    seqUtils,
     stats,
     stringr,
     sysfonts

R/draw_mutation_tree.R

@@ -1,42 +1,82 @@
-#' Draw a mutation annotated tree
+#' Draw a mutation-annotated phylogenetic tree
 #'
-#' @param tree_and_sequences_asr ...
-#' @param file ...
-#' @param width ...
-#' @param height_per_sequence ...
-#' @param lines ...
-#' @param modified_tip_labels ...
-#' @param modified_node_labels ...
-#' @param additional_node_labels ...
-#' @param tip_text_cex ...
-#' @param tip_text_label_color ...
-#' @param tip_text_nudge ...
-#' @param tip_text_adj ...
-#' @param node_text_cex ...
-#' @param node_text_nudge ...
-#' @param node_text_adj ...
-#' @param tip_node_text_aa_mutation_color ...
-#' @param tip_node_text_aa_mutation_special_colors ...
-#' @param tip_node_text_syn_mutation_color ...
-#' @param line_width ...
-#' @param line_color ...
-#' @param line_text_color ...
-#' @param line_text_cex ...
-#' @param line_text_adj ...
-#' @param line_text_nudge ...
-#' @param node_addtext_cex ...
-#' @param node_addtext_color ...
-#' @param node_addtext_nudge ...
-#' @param node_addtext_adj ...
-#' @param node_point_color ...
-#' @param node_point_cex ...
-#' @param edge_color ...
-#' @param edge_width ...
-#' @param x_lim_expand ...
-#' @param y_lim_expand ...
-#' @param node_nums ...
+#' Creates a visualization of a phylogenetic tree with non-synonymous (amino acid)
+#' and synonymous mutations labeled on branches. Supports extensive customization
+#' of labels, colors, and annotations.
 #'
-#' @returns ...
+#' @param tree_and_sequences_asr A tree_and_sequences object with ancestral sequence
+#'   reconstruction, created by \code{convergence::addASRusher()}.
+#' @param file Output file path. If NULL, displays interactively. Supported formats:
+#'   PNG (600 dpi) or PDF.
+#' @param width Figure width in inches. Default: 6.
+#' @param height_per_sequence Height per tip in inches. Total height is calculated
+#'   as \code{height_per_sequence * n_tips}. Default: 0.03.
+#'
+#' @section Annotation parameters:
+#' @param lines List of lists defining horizontal reference lines. Each element:
+#'   \code{list(height, text, line_color, text_color, line_width, text_cex, text_adj, text_nudge)}.
+#' @param modified_tip_labels List of lists to customize tip labels. Each element:
+#'   \code{list(old_label, new_label, text_color, text_cex)}.
+#' @param modified_node_labels List of lists to customize node mutation labels. Each element:
+#'   \code{list(node, text_color, text_cex)}.
+#' @param additional_node_labels List of lists to add extra annotations. Each element:
+#'   \code{list(node, text, text_color, text_cex, text_adj, text_nudge, point_color, point_cex)}.
+#'
+#' @section Tip label styling:
+#' @param tip_text_cex Tip label text size. Default: 0.2.
+#' @param tip_text_label_color Tip label text color. Default: "grey70".
+#' @param tip_text_nudge Tip label position offset as \code{c(x, y)} fraction of plot range. Default: \code{c(0.002, 0)}.
+#' @param tip_text_adj Tip label text justification. Default: \code{c(0, 0.5)}.
+#'
+#' @section Node mutation styling:
+#' @param node_text_cex Node mutation label text size. Default: 0.2.
+#' @param node_text_nudge Node label position offset as \code{c(x, y)} fraction of plot range. Default: \code{c(-0.002, -0.015)}.
+#' @param node_text_adj Node label text justification. Default: \code{c(1, 1)}.
+#' @param tip_node_text_aa_mutation_color Default color for amino acid mutations. Default: "grey30".
+#' @param tip_node_text_aa_mutation_special_colors Named list mapping colors to amino acid positions
+#'   to highlight, e.g. \code{list(red = c(145, 155), blue = c(189))}. Default: H3 epitope positions.
+#' @param tip_node_text_syn_mutation_color Color for synonymous mutation counts. Default: "grey70".
+#'
+#' @section Reference line styling:
+#' @param line_width Width of horizontal reference lines. Default: 0.3.
+#' @param line_color Color of horizontal reference lines. Default: "grey50".
+#' @param line_text_color Color of reference line text. Default: "black".
+#' @param line_text_cex Reference line text size. Default: 1.
+#' @param line_text_adj Reference line text justification. Default: \code{c(1, 1)}.
+#' @param line_text_nudge Reference line text position offset. Default: \code{c(-0.01, -0.003)}.
+#'
+#' @section Additional node annotation styling:
+#' @param node_addtext_cex Additional node label text size. Default: \code{node_text_cex * 4}.
+#' @param node_addtext_color Additional node label text color. Default: "black".
+#' @param node_addtext_nudge Additional node label position offset. Default: \code{c(-0.004, -0.006)}.
+#' @param node_addtext_adj Additional node label text justification. Default: \code{c(1, 1)}.
+#' @param node_point_color Additional node point color. Default: "black".
+#' @param node_point_cex Additional node point size. Default: 0.8.
+#'
+#' @section Tree styling:
+#' @param edge_color Color of tree edges. Default: "grey80".
+#' @param edge_width Width of tree edges. If NULL, uses ape default. Default: NULL.
+#' @param x_lim_expand Plot x-axis expansion as \code{c(left, right)} fractions. Default: \code{c(0.02, 0.2)}.
+#' @param y_lim_expand Plot y-axis expansion as \code{c(bottom, top)} fractions. Default: \code{c(0.02, 0.02)}.
+#' @param node_nums Logical; show node numbers for debugging. Default: FALSE.
+#'
+#' @returns If \code{file} is specified, returns the file path. Otherwise, displays plot interactively.
+#'
+#' @examples
+#' \dontrun{
+#' # Basic usage
+#' draw_mutation_tree(tree_with_asr)
+#'
+#' # Save to file
+#' draw_mutation_tree(tree_with_asr, file = "tree.png")
+#'
+#' # With annotations
+#' draw_mutation_tree(
+#'   tree_with_asr,
+#'   lines = list(list(height = 20, text = "Clade A")),
+#'   modified_tip_labels = list(list(old_label = "seq1", text_color = "red"))
+#' )
+#' }
 #'
 #' @importFrom dplyr filter
 #' @export
@@ -57,13 +97,13 @@ draw_mutation_tree = function(
   tip_text_adj = c(0, 0.5),
 
   node_text_cex = 0.2,
-  node_text_nudge = c(-0.001, -0.001),
+  node_text_nudge = c(-0.002, -0.015),
   node_text_adj = c(1, 1),
 
   tip_node_text_aa_mutation_color = "grey30",
   tip_node_text_aa_mutation_special_colors = list(
-    red = c(145, 155, 156, 158, 159, 189, 193),
-    orange = c(44L, 45L, 46L, 47L, 48L, 50L, 51L, 53L, 54L, 57L, 59L, 62L, 63L, 67L, 75L, 78L, 80L, 81L, 82L, 83L, 86L, 87L, 88L, 91L, 92L, 94L, 96L, 102L, 103L, 109L, 117L, 121L, 122L, 124L, 126L, 128L, 129L, 130L, 131L, 132L, 133L, 135L, 137L, 138L, 140L, 142L, 143L, 144L, 145L, 146L, 150L, 152L, 155L, 156L, 157L, 158L, 159L, 163L, 165L, 167L, 168L, 170L, 171L, 172L, 173L, 174L, 175L, 176L, 177L, 179L, 182L, 186L, 187L, 188L, 189L, 190L, 192L, 193L, 194L, 196L, 197L, 198L, 201L, 203L, 207L, 208L, 209L, 212L, 213L, 214L, 215L, 216L, 217L, 218L, 219L, 226L, 227L, 228L, 229L, 230L, 238L, 240L, 242L, 244L, 246L, 247L, 248L, 260L, 261L, 262L, 265L, 273L, 275L, 276L, 278L, 279L, 280L, 294L, 297L, 299L, 300L, 304L, 305L, 307L, 308L, 309L, 310L, 311L, 312L) # fmt: skip
+    red = seqUtils::h3_epitope_positions[["koel"]],
+    orange = seqUtils::h3_epitope_positions[["wolf"]]
   ),
   tip_node_text_syn_mutation_color = "grey70",
 
@@ -153,20 +193,20 @@ draw_mutation_tree = function(
     )
 
     segments(
-      x0 = 0,
-      x1 = 0 + 0.01 * x_lim[[2]] + 1,
-      y0 = y_lim[[1]] + 0.05 * diff(y_lim),
-      y1 = y_lim[[1]] + 0.05 * diff(y_lim),
+      x0 = 0 + 0.01 * x_lim[[2]],
+      x1 = 0 + 0.01 * x_lim[[2]] + 0.001,
+      y0 = y_lim[[1]] + 0.1 * diff(y_lim),
+      y1 = y_lim[[1]] + 0.1 * diff(y_lim),
       lwd = 0.7,
-      col = "grey60"
+      col = "grey40"
     )
     text(
-      x = 0.5,
-      y = y_lim[[1]] + 0.05 * diff(y_lim),
-      label = "1 mutation",
-      cex = 0.5,
-      adj = c(0.5, -0.5),
-      col = "grey60"
+      x = 0 + 0.01 * x_lim[[2]] + 0.001 / 2,
+      y = y_lim[[1]] + 0.1 * diff(y_lim),
+      label = "1/1000 s/s",
+      cex = 0.3,
+      adj = c(0.5, -0.8),
+      col = "grey40"
     )
 
     # node mutation labels ---
@@ -347,7 +387,7 @@ draw_mutation_tree = function(
       x = ape::node.depth.edgelength(tree_and_sequences_asr$tree)[[node]]
       y = ape::node.height(tree_and_sequences_asr$tree)[[node]]
 
-      if (line_width > 0) {
+      if (point_cex > 0) {
         points(
           x = x,
           y = y,