From 353cf546dfae7c08ce5e5fc102a3ca9e546b6158 Mon Sep 17 00:00:00 2001 From: R script Date: Thu, 9 Jul 2026 10:42:09 +0100 Subject: [PATCH] docs: fix stale v2.0 documentation and remove LLM artefacts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Audit of the documentation surface touched by the 2.0.0 release. Stale/incorrect claims corrected: - Preset docs described the retired bespoke `large` preset (biased Wagner, annealing, reduced cycles); `large` is now an alias of `thorough` with maxReplicates=500. Fixed in MaximizeParsimony roxygen, the SearchControl comment, and the search-algorithm / tree-search vignettes. - `default` preset documented as 12 ratchet cycles; it is 6. - Vignette preset claims about adaptiveStart, ratchetTaper, annealCycles and consensusStableReps contradicted the actual SearchControl defaults / preset values. - MaximizeParsimony profile-parsimony docstring claimed binary-only (max 2 states); multi-state is supported (Carter 1990 / Maddison & Slatkin 1991 / Monte Carlo). ConcordantInformation carried the same stale two-state restriction. - PrepareDataProfile: `bootstrap` attribute documented a `split.sizes` entry it never writes; "with a warning" overstated (only the inapplicable-token simplification emits a message). - WideSample `@return` said "uniform sample"; it returns a Max-Min diverse subset. - fractional-weight default documented as 1000L; it is 1260L (NEWS.md). - Implied-weight fit formula rendered as `k / e + k`; corrected to `k / (e + k)` (propagates to inheriting man pages). LLM artefacts removed: - The "reflects island structure, not a cap" framing in the Completeness section (the "256 is not hard-coded" aside was already removed on the branch tip by #251). - NEWS.md: the "common complaint" defensive aside, the empty "Other improvements" section, and a duplicate PaintCharacters bullet. man/*.Rd regenerated with roxygen2. Not addressed here (left for the maintainer): the "To integrate into 2.0.0 notes" scaffold in NEWS.md now also holds #251's breaking-change bullets, and the "renamed to Morphy()" line is stale since #251 removed Morphy() — final integration of that section is #251's to make. Co-Authored-By: Claude Opus 4.8 --- NEWS.md | 11 ++--------- R/Concordance.R | 6 +----- R/MaximizeParsimony.R | 34 ++++++++++++++++----------------- R/SearchControl.R | 3 +-- R/WideSample.R | 2 +- R/data_manipulation.R | 17 +++++++++-------- man/AdditionTree.Rd | 2 +- man/ConcordantInformation.Rd | 7 +------ man/LengthAdded.Rd | 2 +- man/MaximizeParsimony.Rd | 34 ++++++++++++++++----------------- man/PrepareDataProfile.Rd | 17 +++++++++-------- man/Resample.Rd | 2 +- man/SuccessiveApproximations.Rd | 2 +- man/TreeLength.Rd | 2 +- man/WideSample.Rd | 2 +- vignettes/search-algorithm.Rmd | 19 ++++++++---------- vignettes/tree-search.Rmd | 12 +++++++----- 17 files changed, 77 insertions(+), 97 deletions(-) diff --git a/NEWS.md b/NEWS.md index d0c1605c0..8fa93f015 100644 --- a/NEWS.md +++ b/NEWS.md @@ -133,7 +133,7 @@ - `attr(dataset, "weight")` now accepts non-integer character weights. The C++ scoring engine still stores `int` weights internally; fractional inputs are rescaled to integer with a configurable precision (default - 0.001, controlled by `getOption("TreeSearch.fractional.scale", 1000L)`). + ~0.001, controlled by `getOption("TreeSearch.fractional.scale", 1260L)`). Previously, fractional weights were silently truncated at the Rcpp boundary (e.g. `c(0.5, 1.7)` became `c(0L, 1L)`, dropping 50% / 41% of the respective characters' contributions). Integer weights pass @@ -174,9 +174,6 @@ faster; inapplicable character handling (Brazeau _et al._ 2019) is built in. ### New features -- `PaintCharacters()` colours each character in a morphological dataset by its - most concordant tree edges. - - `ScoreSpectrum()`: Chao1-style landscape coverage estimator. Treats distinct parsimony scores found across replicates as "species" and estimates how thoroughly the parsimony landscape has been sampled (Good-Turing sample @@ -206,8 +203,6 @@ faster; inapplicable character handling (Brazeau _et al._ 2019) is built in. - **MPT enumeration**: after the main search converges, a TBR plateau walk from each pool tree discovers additional most-parsimonious topologies on the same and neighbouring score plateaus, up to `poolMaxSize`. - This addresses a common complaint that the previous implementation returned - only one tree when multiple MPTs exist. - `LeastSquaresTree()` and `LeastSquaresFit()` search for, and fit branch lengths to, the tree that best matches a target distance matrix under a least-squares criterion, reusing the optimised C++ rearrangement @@ -224,7 +219,7 @@ faster; inapplicable character handling (Brazeau _et al._ 2019) is built in. - `attr(dataset, "weight")` now accepts non-integer character weights. The C++ scoring engine still stores `int` weights internally; fractional inputs are rescaled to integer with a configurable precision (default - 0.001, controlled by `getOption("TreeSearch.fractional.scale", 1000L)`). + ~0.001, controlled by `getOption("TreeSearch.fractional.scale", 1260L)`). Previously, fractional weights were silently truncated at the Rcpp boundary (e.g. `c(0.5, 1.7)` became `c(0L, 1L)`, dropping 50% / 41% of the respective characters' contributions). Integer weights pass @@ -401,8 +396,6 @@ faster; inapplicable character handling (Brazeau _et al._ 2019) is built in. - Dataset-adaptive timeout default (1–15 minutes based on dataset size). - Internal modularization of the Shiny app into proper Shiny modules. -## Other improvements - # TreeSearch 1.8.0.9001 (2026-04-23) - Reorder parameters in `Q[A]Col(quality, amount)`. diff --git a/R/Concordance.R b/R/Concordance.R index 800d24d52..2ba797245 100644 --- a/R/Concordance.R +++ b/R/Concordance.R @@ -1002,9 +1002,6 @@ SharedPhylogeneticConcordance <- function(tree, dataset) { #' consistent with a specified phylogenetic tree, and the signal:noise #' ratio of the character matrix implied if the tree is true. #' -#' Presently restricted to datasets whose characters contain a maximum of -#' two parsimony-informative states. -#' #' @return `ConcordantInformation()` returns a named vector with elements: #' #' - `informationContent`: cladistic information content of `dataset` @@ -1018,8 +1015,7 @@ SharedPhylogeneticConcordance <- function(tree, dataset) { #' matrix to the cladistic information content of the tree, a measure of the #' redundancy of the matrix #' - `ignored`: information content of characters whose signal and noise could -#' not be calculated (too many states) and so are not included in the totals -#' above. +#' not be calculated, and so are not included in the totals above. #' #' @inheritParams TreeTools::Renumber #' @inheritParams MaximizeParsimony diff --git a/R/MaximizeParsimony.R b/R/MaximizeParsimony.R index 7050ad79c..cb12c07a5 100644 --- a/R/MaximizeParsimony.R +++ b/R/MaximizeParsimony.R @@ -366,11 +366,8 @@ #' `maxSeconds`, or raise `enumTimeFraction`, for a more complete set. #' \item **TBR-island coverage.** The plateau walk only explores islands of #' equal-score trees that a main-loop replicate actually landed on. MPTs -#' lying in unvisited islands are never enumerated, however large -#' `poolMaxSize` is. Increase `maxReplicates` to seed more islands. Two -#' independent runs (or runs at different `strategy` effort) can therefore -#' return the *same* count if they exhaust the same connected island — this -#' reflects island structure, not a cap. +#' in unvisited islands are never enumerated, however large `poolMaxSize` +#' is; increase `maxReplicates` to seed more islands. #' } #' By default (`collapse = TRUE`), zero-length (unsupported) branches are #' contracted into polytomies and the returned set is deduplicated on the @@ -387,11 +384,10 @@ #' #' Implied weighting is supported natively: set `concavity` to a numeric #' value (e.g.\sspace{}10). -#' Profile parsimony (`concavity = "profile"`) is supported natively: -#' characters are simplified to binary (max 2 informative states), -#' inapplicable tokens are treated as ambiguous, and per-character -#' information profiles are used for scoring -#' \insertCite{Faith2001}{TreeSearch}. +#' Profile parsimony (`concavity = "profile"`) is supported natively. +#' Inapplicable tokens are treated as ambiguous, and each character is scored +#' by its information profile \insertCite{Faith2001}{TreeSearch}; see +#' [`PrepareDataProfile()`] for how multi-state profiles are computed. #' #' @param dataset A phylogenetic data matrix of \pkg{phangorn} class #' \code{phyDat}, whose names correspond to the labels of any accompanying tree. @@ -406,7 +402,7 @@ #' @param concavity Determines the degree to which extra steps beyond the first #' are penalized. Specify a numeric value to use implied weighting #' \insertCite{Goloboff1993}{TreeSearch}; `concavity` specifies _k_ in -#' _k_ / _e_ + _k_. A value of 10 is recommended; +#' _k_ / (_e_ + _k_). A value of 10 is recommended; #' TNT sets a default of 3, but this is too low in some circumstances #' \insertCite{Goloboff2018,Smith2019}{TreeSearch}. #' Better still explore the sensitivity of results under a range of @@ -479,18 +475,20 @@ #' character patterns; `"default"` otherwise.} #' \item{`"sprint"`}{Fast search: 3 ratchet cycles, no drift, minimal #' sectorial. Good for small datasets or quick surveys.} -#' \item{`"default"`}{Balanced: 12 ratchet + sectorial + fusing.} +#' \item{`"default"`}{Balanced: 6 ratchet cycles, sectorial search and +#' fusing.} #' \item{`"thorough"`}{Intensive: 20 ratchet cycles, adaptive #' perturbation, extra sectorial rounds, drift (2 cycles) and 5 Wagner #' starts, outer cycle loop. Best for datasets with 65-119 tips and 100+ #' character patterns; the drift cycles also recover equal-score trees on #' TBR-disconnected islands that random restarts alone miss.} -#' \item{`"large"`}{Large-tree search (>=120 tips): reduced cycle -#' counts scaled for expensive per-replicate cost, no NNI -#' perturbation, single biased Wagner start (Goloboff 2014), larger -#' sector sizes, 1-cycle simulated annealing instead of drift -#' (linear cooling from T=20 to T=0 over 5 phases). Empirically matches -#' or exceeds `"thorough"` at 180 tips across all time budgets.} +#' \item{`"large"`}{Large-tree search (>=120 tips): the `"thorough"` +#' settings with `maxReplicates` raised to 500 to suit the higher +#' per-replicate cost.} +#' \item{`"intensive"`}{Deprecated alias of `"thorough"`, retained for +#' backward compatibility. The extra Wagner starts (5) that once +#' distinguished it are now folded into `"thorough"`, so the two are +#' identical.} #' \item{`"none"`}{Use only the explicitly supplied parameter values.} #' } #' Presets stop on `targetHits` and the `perturbStopFactor` no-improvement diff --git a/R/SearchControl.R b/R/SearchControl.R index 5dd22b191..82ea4d31f 100644 --- a/R/SearchControl.R +++ b/R/SearchControl.R @@ -295,8 +295,7 @@ SearchControl <- function( # Ratchet # Default 12->6 (T-P5d, 2026-06-19): the ratchet was over-provisioned; # halving cycles saved 20-38% wall at zero quality loss on the mid-size EW - # benchmarks. The `large` preset keeps 12 (deliberate large-tree tradeoff, - # T-179) and is unaffected by this formal-default change. + # benchmarks. The `thorough` preset (which `large` now rebases on) sets 20. ratchetCycles = 6L, ratchetPerturbProb = 0.25, ratchetPerturbMode = 0L, diff --git a/R/WideSample.R b/R/WideSample.R index 6694d5bc0..7f698faee 100644 --- a/R/WideSample.R +++ b/R/WideSample.R @@ -85,7 +85,7 @@ #' Default `60`. #' #' @return A `multiPhylo` object of length `min(n, length(trees))` containing -#' a uniform sample of `trees`. +#' a topologically diverse (Max-Min) subset of `trees`. #' If `n == 1`, the single most central tree (the medoid) is returned. #' Attributes of the input (e.g. `score`, `hits_to_best`) are preserved. #' diff --git a/R/data_manipulation.R b/R/data_manipulation.R index db291868e..9166b49e4 100644 --- a/R/data_manipulation.R +++ b/R/data_manipulation.R @@ -37,11 +37,12 @@ #' Maddison & Slatkin (1991), falling back to a Monte Carlo approximation for #' large or complex characters. #' -#' Characters are simplified where necessary, with a warning: -#' - inapplicable tokens will be replaced with the ambiguous token -#' (i.e. `-` \ifelse{html}{\out{→}}{\eqn{\rightarrow}{-->}} `?`); -#' - Ambiguous tokens will be treated as fully ambiguous -#' (i.e. `{02}` \ifelse{html}{\out{→}}{\eqn{\rightarrow}{-->}} `?`) +#' Characters are simplified where necessary: +#' - inapplicable tokens are replaced with the ambiguous token +#' (i.e. `-` \ifelse{html}{\out{→}}{\eqn{\rightarrow}{-->}} `?`), +#' reported with a message; +#' - ambiguous tokens are treated as fully ambiguous +#' (i.e. `{02}` \ifelse{html}{\out{→}}{\eqn{\rightarrow}{-->}} `?`). #' #' @param dataset dataset of class \code{phyDat} #' @param approx Character string controlling how profile information amounts @@ -63,9 +64,9 @@ #' - `informative`: logical specifying which characters contain any #' phylogenetic information. #' -#' - `bootstrap`: The character vector -#' \code{c("info.amounts", "split.sizes")}, indicating attributes to sample -#' when bootstrapping the dataset (e.g. in Ratchet searches). +#' - `bootstrap`: A character vector naming the attributes to resample when +#' bootstrapping the dataset (e.g. in Ratchet searches); `PrepareDataProfile` +#' adds `"info.amounts"`. #' #' `PrepareDataIW` adds the attribute: #' diff --git a/man/AdditionTree.Rd b/man/AdditionTree.Rd index bb3dc3b2c..078886fe9 100644 --- a/man/AdditionTree.Rd +++ b/man/AdditionTree.Rd @@ -13,7 +13,7 @@ AdditionTree(dataset, concavity = Inf, constraint, sequence) \item{concavity}{Determines the degree to which extra steps beyond the first are penalized. Specify a numeric value to use implied weighting \insertCite{Goloboff1993}{TreeSearch}; \code{concavity} specifies \emph{k} in -\emph{k} / \emph{e} + \emph{k}. A value of 10 is recommended; +\emph{k} / (\emph{e} + \emph{k}). A value of 10 is recommended; TNT sets a default of 3, but this is too low in some circumstances \insertCite{Goloboff2018,Smith2019}{TreeSearch}. Better still explore the sensitivity of results under a range of diff --git a/man/ConcordantInformation.Rd b/man/ConcordantInformation.Rd index b2d503254..fcc2a5ca6 100644 --- a/man/ConcordantInformation.Rd +++ b/man/ConcordantInformation.Rd @@ -32,8 +32,7 @@ a bifurcating tree, assuming no duplicate information or noise matrix to the cladistic information content of the tree, a measure of the redundancy of the matrix \item \code{ignored}: information content of characters whose signal and noise could -not be calculated (too many states) and so are not included in the totals -above. +not be calculated, and so are not included in the totals above. } } \description{ @@ -41,10 +40,6 @@ Details the amount of information in a phylogenetic dataset that is consistent with a specified phylogenetic tree, and the signal:noise ratio of the character matrix implied if the tree is true. } -\details{ -Presently restricted to datasets whose characters contain a maximum of -two parsimony-informative states. -} \examples{ data(congreveLamsdellMatrices) myMatrix <- congreveLamsdellMatrices[[10]] diff --git a/man/LengthAdded.Rd b/man/LengthAdded.Rd index d01bc99a0..8da377732 100644 --- a/man/LengthAdded.Rd +++ b/man/LengthAdded.Rd @@ -17,7 +17,7 @@ PolEscapa(trees, char, concavity = Inf) \item{concavity}{Determines the degree to which extra steps beyond the first are penalized. Specify a numeric value to use implied weighting \insertCite{Goloboff1993}{TreeSearch}; \code{concavity} specifies \emph{k} in -\emph{k} / \emph{e} + \emph{k}. A value of 10 is recommended; +\emph{k} / (\emph{e} + \emph{k}). A value of 10 is recommended; TNT sets a default of 3, but this is too low in some circumstances \insertCite{Goloboff2018,Smith2019}{TreeSearch}. Better still explore the sensitivity of results under a range of diff --git a/man/MaximizeParsimony.Rd b/man/MaximizeParsimony.Rd index 23326b360..02e6a38b2 100644 --- a/man/MaximizeParsimony.Rd +++ b/man/MaximizeParsimony.Rd @@ -44,7 +44,7 @@ Edge lengths are not supported and will be deleted.} \item{concavity}{Determines the degree to which extra steps beyond the first are penalized. Specify a numeric value to use implied weighting \insertCite{Goloboff1993}{TreeSearch}; \code{concavity} specifies \emph{k} in -\emph{k} / \emph{e} + \emph{k}. A value of 10 is recommended; +\emph{k} / (\emph{e} + \emph{k}). A value of 10 is recommended; TNT sets a default of 3, but this is too low in some circumstances \insertCite{Goloboff2018,Smith2019}{TreeSearch}. Better still explore the sensitivity of results under a range of @@ -125,18 +125,20 @@ character patterns; \code{"thorough"} for 65-119 taxa with >=100 character patterns; \code{"default"} otherwise.} \item{\code{"sprint"}}{Fast search: 3 ratchet cycles, no drift, minimal sectorial. Good for small datasets or quick surveys.} -\item{\code{"default"}}{Balanced: 12 ratchet + sectorial + fusing.} +\item{\code{"default"}}{Balanced: 6 ratchet cycles, sectorial search and +fusing.} \item{\code{"thorough"}}{Intensive: 20 ratchet cycles, adaptive perturbation, extra sectorial rounds, drift (2 cycles) and 5 Wagner starts, outer cycle loop. Best for datasets with 65-119 tips and 100+ character patterns; the drift cycles also recover equal-score trees on TBR-disconnected islands that random restarts alone miss.} -\item{\code{"large"}}{Large-tree search (>=120 tips): reduced cycle -counts scaled for expensive per-replicate cost, no NNI -perturbation, single biased Wagner start (Goloboff 2014), larger -sector sizes, 1-cycle simulated annealing instead of drift -(linear cooling from T=20 to T=0 over 5 phases). Empirically matches -or exceeds \code{"thorough"} at 180 tips across all time budgets.} +\item{\code{"large"}}{Large-tree search (>=120 tips): the \code{"thorough"} +settings with \code{maxReplicates} raised to 500 to suit the higher +per-replicate cost.} +\item{\code{"intensive"}}{Deprecated alias of \code{"thorough"}, retained for +backward compatibility. The extra Wagner starts (5) that once +distinguished it are now folded into \code{"thorough"}, so the two are +identical.} \item{\code{"none"}}{Use only the explicitly supplied parameter values.} } Presets stop on \code{targetHits} and the \code{perturbStopFactor} no-improvement @@ -306,11 +308,8 @@ returns a \emph{partial} set (the run reports \code{stop = "timeout"}); allow mo \code{maxSeconds}, or raise \code{enumTimeFraction}, for a more complete set. \item \strong{TBR-island coverage.} The plateau walk only explores islands of equal-score trees that a main-loop replicate actually landed on. MPTs -lying in unvisited islands are never enumerated, however large -\code{poolMaxSize} is. Increase \code{maxReplicates} to seed more islands. Two -independent runs (or runs at different \code{strategy} effort) can therefore -return the \emph{same} count if they exhaust the same connected island — this -reflects island structure, not a cap. +in unvisited islands are never enumerated, however large \code{poolMaxSize} +is; increase \code{maxReplicates} to seed more islands. } By default (\code{collapse = TRUE}), zero-length (unsupported) branches are contracted into polytomies and the returned set is deduplicated on the @@ -327,11 +326,10 @@ topology). Implied weighting is supported natively: set \code{concavity} to a numeric value (e.g.\sspace{}10). -Profile parsimony (\code{concavity = "profile"}) is supported natively: -characters are simplified to binary (max 2 informative states), -inapplicable tokens are treated as ambiguous, and per-character -information profiles are used for scoring -\insertCite{Faith2001}{TreeSearch}. +Profile parsimony (\code{concavity = "profile"}) is supported natively. +Inapplicable tokens are treated as ambiguous, and each character is scored +by its information profile \insertCite{Faith2001}{TreeSearch}; see +\code{\link[=PrepareDataProfile]{PrepareDataProfile()}} for how multi-state profiles are computed. } \examples{ diff --git a/man/PrepareDataProfile.Rd b/man/PrepareDataProfile.Rd index 072f2e65b..8fbb533bf 100644 --- a/man/PrepareDataProfile.Rd +++ b/man/PrepareDataProfile.Rd @@ -32,9 +32,9 @@ An object of class \code{phyDat}, with additional attributes. character when subject to N additional steps. \item \code{informative}: logical specifying which characters contain any phylogenetic information. -\item \code{bootstrap}: The character vector -\code{c("info.amounts", "split.sizes")}, indicating attributes to sample -when bootstrapping the dataset (e.g. in Ratchet searches). +\item \code{bootstrap}: A character vector naming the attributes to resample when +bootstrapping the dataset (e.g. in Ratchet searches); \code{PrepareDataProfile} +adds \code{"info.amounts"}. } \code{PrepareDataIW} adds the attribute: @@ -52,12 +52,13 @@ Maddison & Slatkin (1991), falling back to a Monte Carlo approximation for large or complex characters. } \details{ -Characters are simplified where necessary, with a warning: +Characters are simplified where necessary: \itemize{ -\item inapplicable tokens will be replaced with the ambiguous token -(i.e. \code{-} \ifelse{html}{\out{→}}{\eqn{\rightarrow}{-->}} \verb{?}); -\item Ambiguous tokens will be treated as fully ambiguous -(i.e. \code{{02}} \ifelse{html}{\out{→}}{\eqn{\rightarrow}{-->}} \verb{?}) +\item inapplicable tokens are replaced with the ambiguous token +(i.e. \code{-} \ifelse{html}{\out{→}}{\eqn{\rightarrow}{-->}} \verb{?}), +reported with a message; +\item ambiguous tokens are treated as fully ambiguous +(i.e. \code{{02}} \ifelse{html}{\out{→}}{\eqn{\rightarrow}{-->}} \verb{?}). } } \section{Functions}{ diff --git a/man/Resample.Rd b/man/Resample.Rd index 142f9f750..e1ad9fea4 100644 --- a/man/Resample.Rd +++ b/man/Resample.Rd @@ -62,7 +62,7 @@ underlying search engine's \code{tbrMaxHits} control).} \item{concavity}{Determines the degree to which extra steps beyond the first are penalized. Specify a numeric value to use implied weighting \insertCite{Goloboff1993}{TreeSearch}; \code{concavity} specifies \emph{k} in -\emph{k} / \emph{e} + \emph{k}. A value of 10 is recommended; +\emph{k} / (\emph{e} + \emph{k}). A value of 10 is recommended; TNT sets a default of 3, but this is too low in some circumstances \insertCite{Goloboff2018,Smith2019}{TreeSearch}. Better still explore the sensitivity of results under a range of diff --git a/man/SuccessiveApproximations.Rd b/man/SuccessiveApproximations.Rd index 9d6d41a38..9d2bd5c4c 100644 --- a/man/SuccessiveApproximations.Rd +++ b/man/SuccessiveApproximations.Rd @@ -60,7 +60,7 @@ than the optimal tree.} \item{concavity}{Determines the degree to which extra steps beyond the first are penalized. Specify a numeric value to use implied weighting \insertCite{Goloboff1993}{TreeSearch}; \code{concavity} specifies \emph{k} in -\emph{k} / \emph{e} + \emph{k}. A value of 10 is recommended; +\emph{k} / (\emph{e} + \emph{k}). A value of 10 is recommended; TNT sets a default of 3, but this is too low in some circumstances \insertCite{Goloboff2018,Smith2019}{TreeSearch}. Better still explore the sensitivity of results under a range of diff --git a/man/TreeLength.Rd b/man/TreeLength.Rd index 59cf0793b..4f76a73fb 100644 --- a/man/TreeLength.Rd +++ b/man/TreeLength.Rd @@ -85,7 +85,7 @@ uniformly sampled.} \item{concavity}{Determines the degree to which extra steps beyond the first are penalized. Specify a numeric value to use implied weighting \insertCite{Goloboff1993}{TreeSearch}; \code{concavity} specifies \emph{k} in -\emph{k} / \emph{e} + \emph{k}. A value of 10 is recommended; +\emph{k} / (\emph{e} + \emph{k}). A value of 10 is recommended; TNT sets a default of 3, but this is too low in some circumstances \insertCite{Goloboff2018,Smith2019}{TreeSearch}. Better still explore the sensitivity of results under a range of diff --git a/man/WideSample.Rd b/man/WideSample.Rd index b5fa2d301..045ef6214 100644 --- a/man/WideSample.Rd +++ b/man/WideSample.Rd @@ -43,7 +43,7 @@ Default \code{60}.} } \value{ A \code{multiPhylo} object of length \code{min(n, length(trees))} containing -a uniform sample of \code{trees}. +a topologically diverse (Max-Min) subset of \code{trees}. If \code{n == 1}, the single most central tree (the medoid) is returned. Attributes of the input (e.g. \code{score}, \code{hits_to_best}) are preserved. } diff --git a/vignettes/search-algorithm.Rmd b/vignettes/search-algorithm.Rmd index d5e1ec076..bd19ab6b2 100644 --- a/vignettes/search-algorithm.Rmd +++ b/vignettes/search-algorithm.Rmd @@ -194,9 +194,7 @@ replicates, ensuring diversity without lock overhead. Enabling `adaptiveStart` is most valuable for medium-to-large datasets where many replicates complete and the bandit has time to learn. -For very large datasets ($\geq$ 120 tips) where only a few replicates -complete within the time budget, the bandit has insufficient data and -`adaptiveStart` is disabled in the `large` preset. +The `thorough` and `large` presets enable it. Per-strategy attempt and success counts are returned in the `strategy_diagnostics` attribute of the search result for post-hoc @@ -328,9 +326,8 @@ extensively (it is an artefact), so perturbed-phase TBR should be brief, but the perturbation itself must be aggressive enough to displace the tree from its current basin. -When `ratchetTaper = TRUE` (enabled by default in the `thorough` and `large` -presets), the perturbation probability is tapered across replicates as the -tree pool stabilizes. +When `ratchetTaper = TRUE` (off by default), the perturbation probability is +tapered across replicates as the tree pool stabilizes. Early replicates use the full perturbation probability; later replicates, when most replicates converge to the same score, use a reduced probability for finer local exploration of the current basin. @@ -387,8 +384,7 @@ This best-tree restart strategy distinguishes PCSA from a simple annealing schedule: the SA phase is used purely as a perturbation mechanism (analogous to the ratchet), not as a global optimizer. The number of SA + TBR cycles per replicate is controlled by -`annealCycles` (default 0 = disabled; the `large` strategy preset -sets 3). +`annealCycles` (default 0 = disabled; not enabled by any preset). ## Sectorial search @@ -506,9 +502,10 @@ replicates. After each replicate, the strict consensus of the pool's best-score trees is hashed (XOR of per-split FNV-1a hashes). If the consensus hash is unchanged for `consensusStableReps` consecutive -replicates (default 3 in all presets), the search terminates. +replicates, the search terminates. This provides a data-adaptive stopping criterion: easy datasets converge quickly, while hard datasets continue searching. +It is disabled (`0`) by default; see below. ### Adaptive search level @@ -545,8 +542,8 @@ dataset size: |-------------|---------------------------------------------|-----------------------------------| | `sprint` | $\leq$ 30 tips | Minimal ratchet, no drift | | `default` | 31--64 tips, or $\geq$ 65 with < 100 patterns | Balanced; adaptive search level | -| `thorough` | $\geq$ 65 tips with $\geq$ 100 patterns | High-intensity; NNI perturbation, outer cycles | -| `large` | $\geq$ 120 tips with $\geq$ 200 patterns | Biased Wagner, large sectors | +| `thorough` | $\geq$ 65 tips with $\geq$ 100 patterns | High-intensity; drift, outer cycles | +| `large` | $\geq$ 120 tips with $\geq$ 100 patterns | As `thorough`, with more replicates | The signal-density gate (character pattern count) prevents the `thorough` preset from being selected for datasets with flat parsimony landscapes where diff --git a/vignettes/tree-search.Rmd b/vignettes/tree-search.Rmd index fef9f8750..846f8b972 100644 --- a/vignettes/tree-search.Rmd +++ b/vignettes/tree-search.Rmd @@ -260,12 +260,14 @@ The `strategy` parameter selects a named preset that configures the search pipeline. The default, `"auto"`, selects a preset based on dataset size: -- `"sprint"` (≤ 30 taxa): fast search with minimal ratchet, no drift. +- `"sprint"` (≤ 30 taxa): fast search with minimal ratchet. Good for small or simple datasets. -- `"default"` (31--60 taxa): balanced search with ratchet, drift, and - sectorial search. -- `"thorough"` (> 60 taxa): intensive search with more ratchet and drift - cycles, adaptive ratchet perturbation, and more sectorial search rounds. +- `"default"` (31--64 taxa, or any dataset with < 100 character patterns): + balanced ratchet and sectorial search. +- `"thorough"` (≥ 65 taxa with ≥ 100 patterns): intensive search adding + drift cycles, adaptive ratchet perturbation, more sectorial rounds, and an + outer cycle loop. +- `"large"` (≥ 120 taxa): the `"thorough"` settings with more replicates. You can override the auto-selection: