expanded_tree_from_jplace: Place queries on a tree from a jplace file.

In castor: Efficient Phylogenetics on Large Trees

Place queries on a tree from a jplace file.

Description

Given a jplace file (e.g., as generated by pplacer or EPA-NG), construct an expanded tree consisting of the original reference tree and additional tips representing the placed query sequences. The reference tree and placements are loaded from the jplace file. If multiple placements are listed for a query, this function can either add the best (maximum-likelihood) placement or all listed placements.

Usage

expanded_tree_from_jplace(file_path,
                          only_best_placements  = TRUE,
                          max_names_per_query   = 1,
                          max_pendant_length    = Inf,
                          min_like_weight_ratio = 0)

Arguments

file_path	Character, the path to the input jplace file. May be gzipped with file extension ".gz".
only_best_placements	Logical, only keep the best placement of each query, i.e., the placement with maximum likelihood.
max_names_per_query	Positive integer, maximum number of sequence names to keep from each query. Only relevant if queries in the jplace file include multiple sequence names (these typically represent identical sequences). If greater than 1, and a query includes multiple sequence names, then each of these sequence names will be added as a tip to the tree.
max_pendant_length	Positive numeric, optional maximum acceptable placement pendant length. Any placements exceeding this pendant length are omitted. If only_best_placements==TRUE, then this filter is applied after selecting the best placement.
min_like_weight_ratio	Numeric between 0 and 1, optional minimum acceptable placement likelihood weight ratio. Any placements below this threshold are omitted. If only_best_placements==TRUE, then this filter is applied after selecting the best placement.

Details

This function assumes version 3 of the jplace file format, as defined by Matsen et al. (2012).

Value

A named list with the following elements:

tree	Object of class "phylo", the extended tree constructed by adding the placements on the reference tree.
placed_tips	Integer vector, specifying which tips in the returned tree correspond to placements.
pendant_lengths	Integer vector, specifying the edge lengths leading into the placed tips. This will be synchronized with the returned vector placed_tips.
loglikelihoods	Numeric vector, specifying the placement log-likelihoods loaded from the jplace file. This will be synchronized with the returned vector placed_tips.
like_weight_ratios	Numeric vector, specifying the placement likelihood weight ratios loaded from the jplace file (Matsen et al. 2012). This will be synchronized with the returned vector placed_tips.
reference_tree	Object of class "phylo", the original reference tree loaded from the jplace file. This will be a subtree of tree.
reference_edges	Integer vector, listing the edge indices in the reference tree onto which the placements were performed. This vector is synchronized with the returned placed_tips, and the listed indices refer to edges in the returned referece_tree.
NPfiltered	Integer, number of placements that have been filtered out due to quality criteria such as max_pendant_length and min_like_weight_ratio.

Author(s)

Stilianos Louca

References

Frederick A. Matsen et al. (2012). A format for phylogenetic placements. PLOS One. 7:e31009

See Also

place_tips_taxonomically

Examples

## Not run: 
# load jplace file and create expanded tree
J = expanded_tree_from_jplace("epa_ng_output.jplace")

# save the reference and expanded tree as Newick files
write_tree(J$reference_tree, file="reference.tre")
write_tree(J$tree, file="expanded.tre")

## End(Not run)

castor documentation built on Jan. 21, 2026, 9:08 a.m.