place_tips_taxonomically: Place queries on a tree based on taxonomic identities.

In castor: Efficient Phylogenetics on Large Trees

Place queries on a tree based on taxonomic identities.

Description

Given a rooted tree with associated tip & node taxonomies, as well as a list of query taxonomies, place the queries on nodes of the tree based on taxonomic identity. Loosely speaking, each query is placed at the shallowest possible node (furthest from the root in terms of splits) for which it is certain that the query is a descendant of (see below for details).

Usage

place_tips_taxonomically( tree,
                          query_labels,
                          query_taxonomies      = NULL,
                          tip_taxonomies        = NULL,
                          node_taxonomies       = NULL,
                          tree_taxon_delimiter  = ";",
                          query_taxon_delimiter = ";",
                          include_expanded_tree = TRUE,
                          placement_length      = "mean_depth")

Arguments

tree	Rooted tree of class "phylo".
query_labels	Character vector of length Nqueries, listing labels for the newly placed tips.
query_taxonomies	Optional character vector of length Nqueries, listing the taxonomic paths of the queries. If NULL, it is assumed that query_labels are taxonomies.
tip_taxonomies	Optional character vector of length Ntips, listing taxonomic paths for the tree's tips. If NULL, then tip labels are assumed to be tip taxonomies.
node_taxonomies	Optional character vector of length Nnodes, listing taxonomic paths for the tree's nodes. If NULL, then node labels are assumed to be node taxonomies.
tree_taxon_delimiter	Character, the delimiter between taxonomic levels in the tree's tip & node taxonomies (e.g., ";" for SILVA taxonomies).
query_taxon_delimiter	Character, the delimiter between taxonomic levels in query_taxonomies.
include_expanded_tree	If TRUE, the expanded tree (i.e., including the placements) is returned as well, at some computational cost. If FALSE, only the placement info is returned, but no tree expansion is done.
placement_length	Character or numeric, specifying how to determine the edge length leading into each placed query. Options are "mean_depth" (mean distance of the placement node to any of its descending tips), "max_depth" (maximum distance of the placement node to any of its descending tips), "min_depth" (minimum distance of the placement node to any of its descending tips) or any non-negative numeric value (fixed edge length). Only relevant if the tree has edge lengths and if include_expanded_tree==TRUE.

Details

Each query is placed at the most recent common ancestor (MRCA) of all possible ancestral nodes with maximal height (PAMH nodes) and maximum taxonomic precision. A node is considered a PAMH node if and only if the query could in principle descend from that node (based on the provided node and query taxonomies) but surely cannot descend from any of the node's child nodes. The taxonomic precision of a node is the number of meaningful available taxonomic levels; only PAMH nodes with the highest taxonomic precision are considered for the MRCA.

This function only makes sense if the tip & node taxonomies are somewhat consistent with each other and with the tree's topology.

Value

A named list with the following elements:

placement_nodes

Integer vector of length Nqueries, with values in 1,..,Nnodes, specifying for each query the node on which it was placed. For queries that could not be placed on the tree, the value 0 is used.

If include_expanded_tree was TRUE, the following additional elements are included:

tree	Object of class "phylo", the extended tree constructed by adding the placements on the original tree.
placed_tips	Integer vector of length Nqueries, specifying the newly placed tips in the expanded tree, in the same order as the original provided queries. For queries that could not be placed on the tree, the value 0 is used.

Author(s)

Stilianos Louca

See Also

expanded_tree_from_jplace

castor documentation built on July 24, 2026, 9:10 a.m.