bijux-phylogenetics

Canonical runtime package for the bijux-phylogenetics repository.

This package is the public Python API and CLI for tree validation, alignment handling, comparative trait analysis, ancestral-state reconstruction, discrete-state evolution analysis, external-engine orchestration, native likelihood and inference, Bayesian posterior summarization, diversification review, evidence bundles, explicit parsimony scoring, and HTML report generation.

Choose this package when you want the full runtime contract rather than the shorter compatibility alias.

Package Structure At A Glance

• runtime package
• CLI workflows
• workflow Python API
• native runtime contracts
• likelihood foundations
• maximum-likelihood inference
• Bayesian inference
• benchmark contracts

Install

bijux-phylogenetics supports Python 3.11 and newer.

python3.11 -m pip install bijux-phylogenetics
bijux-phylogenetics --help

The installed runtime also ships packaged example inputs:

from pathlib import Path

from bijux_phylogenetics.core import copy_example_inputs

copy_example_inputs(Path("artifacts/example-inputs"))

What This Package Already Covers

Why The Package Is Deeper Than A Typical Wrapper Toolkit

The package surface is broad because it joins several families that often live in separate projects:

• owned tree and topology semantics
• workflow APIs that emit typed, reviewable results
• native maximum-likelihood and supported native Bayesian public surfaces
• comparative, ancestral, and parsimony families
• packaged datasets, example inputs, reports, and benchmark contracts

Why This Package Is Not Just A Wrapper

• it owns the PhyloTree runtime and the topology, support, and tree-distance semantics that sit underneath multiple workflows
• it exposes typed Python workflow results with stable artifact writers instead of only printing shell output
• it includes native maximum-likelihood tree inference results and native Bayesian public inference entry points as documented public surfaces
• it keeps wrapper-backed orchestration honest by separating native ownership from external-engine execution

Flagship User Paths

• use the CLI when you want one governed workflow with durable files
• use bijux_phylogenetics.api when you want typed workflow results in Python
• use native likelihood or Bayesian modules when you want lower-level owned runtime contracts
• use the benchmark and evidence-book guides when you need trust-oriented review rather than only execution

Public Runtime Families

The public runtime families are:

• CLI workflows
• workflow Python APIs
• native runtime modules
• comparative analysis
• reports and artifacts

Python Workflow Surface

The stable notebook-and-pipeline surface lives under bijux_phylogenetics.api.

It exposes typed workflow results for:

• FASTA validation
• multiple-sequence alignment
• alignment trimming
• full FASTA-to-tree execution
• maximum-likelihood tree inference
• branch-support estimation
• topology comparison
• PGLS comparative modeling
• discrete ancestral reconstruction
• reviewer-facing report generation
• config-driven workflow execution

from pathlib import Path

from bijux_phylogenetics.api import (
    render_report_workflow,
    run_comparative_model_workflow,
    run_sequence_to_tree_workflow,
)

workflow = run_sequence_to_tree_workflow(
    Path("dataset/sequences.fasta"),
    out_dir=Path("artifacts/sequence-to-tree"),
    sequence_type="dna",
)

comparative = run_comparative_model_workflow(
    Path("dataset/tree.nwk"),
    Path("dataset/traits.tsv"),
    response="response",
    predictors=["predictor_one"],
    lambda_value=1.0,
)

report = render_report_workflow(
    tree_path=workflow.output_paths["tree"],
    alignment_path=workflow.output_paths["trimmed_alignment"],
    traits_path=Path("dataset/traits.tsv"),
    metadata_path=Path("dataset/metadata.tsv"),
    out_path=Path("artifacts/sequence-to-tree/report.html"),
)

workflow.write_json(Path("artifacts/sequence-to-tree/workflow.json"))
workflow.write_tsv(Path("artifacts/sequence-to-tree/workflow.tsv"))
comparative.write_tsv(Path("artifacts/comparative-model.tsv"))

Native Inference And Benchmark Surfaces

Native Inference And Benchmark Surfaces are part of the public package contract.

Public native surfaces include:

• bijux_phylogenetics.phylo.likelihood.infer_nucleotide_maximum_likelihood_result(...)
• bijux_phylogenetics.phylo.likelihood.infer_nucleotide_maximum_likelihood_result_from_alignment(...)
• bijux_phylogenetics.phylo.likelihood.NucleotideMaximumLikelihoodResult
• bijux_phylogenetics.bayesian.run_bayesian_inference(...)
• bijux_phylogenetics.benchmark.benchmark_native_maximum_likelihood_suite(...)

These surfaces matter because the package now owns native maximum-likelihood tree inference results, native Bayesian public inference entry points, and benchmark review contracts in addition to the higher-level workflow wrappers.

Representative public runtime surfaces include:

• bijux_phylogenetics.api.run_sequence_to_tree_workflow(...)
• bijux_phylogenetics.api.run_comparative_model_workflow(...)
• bijux_phylogenetics.compare.topology
• bijux_phylogenetics.phylo.likelihood
• bijux_phylogenetics.bayesian
• bijux_phylogenetics.benchmark

Public Reading Rule

Runtime breadth and evidence closure are related, but they are not the same claim.

• A documented runtime surface is usable.
• A native surface is locally implemented rather than only wrapped.
• A study or benchmark surface explains how much trust that claim currently carries.

That separation is deliberate. The package can expose substantial runtime depth without pretending that every surrounding scientific claim is already closed by the evidence-book.

Read This Next

• Surface selection guide
• Artifact consumption guide
• Native Inference And Benchmark Surfaces
• Native maximum-likelihood workflows
• Native Bayesian workflows
• Native benchmark review
• Runtime architecture
• Release review workflow
• Evidence-book guide