Kuhner-Felsenstein distance

Branch score distance between trees (topology + branch lengths)

Command identity

Canonical command:

kf_distance

Handler:

kf_distance

Aliases:

kf, kf_dist, kuhner_felsenstein_distance

Standalone executables:

pk_kf_distance, pk_kf, pk_kf_dist, pk_kuhner_felsenstein_distance

Categories:

Tree comparison & consensus

Runtime interface

Synopsis

phykit kf_distance <tree_zero> <tree_one> [--json]

Arguments

This table is generated from the live command parser. It is the authoritative source for accepted spellings, required arguments, types, defaults, and choices.

Argument	Required	Type	Default	Choices
tree_zero	true	str	required	any
tree_one	true	str	required	any
--json	false	boolean	false	any

Output and errors

--json provides the command's structured JSON representation. Unless the guidance below states otherwise, results are emitted as command output. Invalid command syntax exits with status 2. Input validation and scientific limitations are described in the guidance below.

Guidance, interpretation, and examples

Calculate the Kuhner-Felsenstein (KF) branch score distance between two trees.

Unlike Robinson-Foulds distance which only considers topology, KF distance incorporates both topology and branch length differences. The KF distance is calculated as KF = sqrt(sum over all splits of (b1_i - b2_i)^2), where b1_i and b2_i are branch lengths for split i in each tree. Splits absent from one tree use branch length 0. Both internal and terminal branches are included.

PhyKIT will print out col 1: the plain KF distance and col 2: the normalized KF distance.

KF distances are calculated following Kuhner & Felsenstein, Journal of Computational Biology (1994), doi: 10.1089/cmb.1994.1.183.

Cross-validated against R's phangorn::KF.dist().

phykit kf_distance <tree_file_zero> <tree_file_one> [--json]

Options:
<tree_file_zero>: first argument after function name should be a tree file
<tree_file_one>: second argument after function name should be a tree file
--json: optional argument to print results as JSON

R validation: Validated against phangorn in R (see tests/r_validation/validate_kf_distance.R).