Tree builder¶
damicore_tree_builder builds a deterministic Neighbor Joining tree from a distance matrix and writes it in Newick form.
Functions¶
- damicore_tree_builder.build_tree(matrix_path: str | Path, labels_path: str | Path, output_dir: str | Path, *, config: TreeBuildConfig | None = None) TreeBuildResult¶
Build and persist a deterministic Neighbor Joining tree.
Takes
distance.npyandlabels.jsonas the distance stage writes them, and writestree.jsonandtree.nwkintooutput_dir; both must be absent, since a tree is never overwritten.output_diris created before that check, so even a rejected call leaves the directory behind. Joining runs against a privatetree-work.npymemory map insideoutput_dir, so the input matrix is left untouched and peak RAM does not grow with the matrix; once that workspace exists it is removed on every exit path, but a failure while creating it, a full disk being the realistic one, can leave it behind. The two artifacts are re-read and validated after writing, and deleted again if that fails, so a rejected tree never survives to block the next run. Ties in the Q criterion are broken by label order, which makes the output a function of the matrix and its labels alone. Negative branch lengths are reported in the result, never clamped.tree.jsonis the inputdamicore_clusterizer.cluster_tree()expects.- Raises:
TreeBuilderError –
tree.jsonortree.nwkalready exists (output_directory_conflict_error); the labels artifact or the persisted tree is invalid, or the edges form a cycle (artifact_validation_error); the matrix is unreadable, mis-shaped, non-finite, or not symmetric with a zero diagonal (distance_matrix_validation_error).
Models¶
- class damicore_tree_builder.Tree(*, schema_version: Literal[1] = 1, root_id: str, nodes: tuple[TreeNode, ...], edges: tuple[TreeEdge, ...])¶
- schema_version: Literal[1]¶
- class damicore_tree_builder.TreeBuildResult(*, tree_path: Path, newick_path: Path, leaf_count: Annotated[int, Ge(ge=0)], negative_branch_count: Annotated[int, Ge(ge=0)], timing: Annotated[float, Ge(ge=0)])¶
- tree_path: Path¶
- newick_path: Path¶