Phylogenomics Tools Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/app/services/(phylogenomics)/gene-protein-tree/page.tsx
• src/lib/forms/(phylogenomics)/viral-genome-tree/tests/viral-genome-tree-form-utils.test.ts
• src/lib/services/service-info.ts
• src/components/navbars/navbar-links.ts
• src/constants/datafields/genome_sequence.ts
• src/constants/datafields/genome.ts

The Phylogenomics Tools Integration provides a suite of services for constructing custom phylogenetic trees from user-selected genomes, genes, or proteins. These tools support diverse evolutionary models and tree-building algorithms to infer accurate phylogenetic topologies. The integration is categorized within the project's service architecture alongside Genomics, Metagenomics, and Viral Tools.

The system facilitates the construction of trees based on either nucleotide (DNA) or protein sequences. It integrates several high-performance algorithms, including FastTree for large minimum evolution trees, and PhyML or RAxML for maximum likelihood inference. The output is typically a Newick file format, which can be visualized using the interactive Archaeopteryx Tree Viewer or downloaded for external analysis.

Sources: [src/lib/services/service-info.ts:543-556], [src/components/navbars/navbar-links.ts:108-117]

Service Overview and Navigation

Phylogenomics services are organized into two primary categories in the application's navigation structure:

• Gene/Protein Tree: For building trees based on individual genetic features or protein sequences.
• Viral Genome Tree: Specifically tailored for viral genomic data.

Sources: [src/components/navbars/navbar-links.ts:108-117]

Data Flow Architecture

The following diagram illustrates the high-level data flow from user input to job submission for a phylogenomics analysis.

The application manages sequence selection, model configuration, and metadata inclusion before transforming data for the backend API.
Sources: [src/app/services/(phylogenomics)/gene-protein-tree/page.tsx:156-200], [src/lib/services/service-info.ts:558-578]

Input Configuration and Validation

The integration supports multiple input sources, including workspace files, pasted sequences, and feature/genome groups.

Input Category	Description	Supported Types
DNA/Protein Aligned	Uploaded aligned sequence FASTA files.	.fasta, .fa
Unaligned FASTA	Raw sequence files requiring alignment.	feature_dna_fasta, feature_protein_fasta
Feature Group	Collections of genes/proteins from the workspace.	feature_group
Genome Group	Collections of genomes from the workspace.	genome_group

Sources: [src/lib/services/service-info.ts:560-575], [src/app/services/(phylogenomics)/gene-protein-tree/page.tsx:244-255]

Validation Logic

The system enforces strict validation on inputs to ensure job success:

1. Alphabet Consistency: Users cannot mix DNA and Protein files in the same tree. Switching the alphabet triggers a cleanup of incompatible sequences.
2. Sequence Limits: The system typically limits the number of sequences (e.g., a maximum of 100 for some maximum likelihood configurations or up to 5000 for others).
3. Duplicate Checking: Prevents adding the same filename and sequence type multiple times to the analysis set.

Sources: [src/app/services/(phylogenomics)/gene-protein-tree/page.tsx:162-178], [src/lib/forms/(phylogenomics)/viral-genome-tree/__tests__/viral-genome-tree-form-utils.test.ts:55-104]

Algorithm and Model Selection

Users must define the evolutionary substitution model and the specific tree-building algorithm.

Tree Algorithms

Algorithm	Method	Best Use Case
FastTree	Minimum Evolution	Large datasets; computes trees with profiles instead of distance matrices.
PhyML	Maximum Likelihood	Evolutionarily accurate topologies; best for < 1000 sequences.
RAxML	Maximum Likelihood	High accuracy; preferred for smaller datasets with long sequences.

Sources: [src/lib/services/service-info.ts:545-554], [src/lib/services/service-info.ts:598-603]

Substitution Models

The available models are dynamically filtered based on the selected sequence alphabet (DNA vs. Protein).

Metadata Integration

The phylogenomics tools allow users to map metadata fields to the resulting tree for enhanced visualization in tools like phyloxml.

Available Metadata Fields

Commonly integrated fields include:

• Genome Info: genome_name, genome_id, strain, accession.
• Taxonomy Info: taxon_id, species, genus, lineage.
• Host Info: host_name, host_common_name, host_gender, host_age.
• Isolate Info: isolation_country, collection_date, collection_year.

Sources: [src/constants/datafields/genome.ts:6-330], [src/constants/datafields/genome_sequence.ts:2-42]

Implementation Details

Metadata labels are formatted from database keys (e.g., genome_name becomes "Genome Name") and are grouped into categories such as "General Info," "Taxonomy Info," and "Host Info" for user selection.

Sources: [src/lib/forms/(phylogenomics)/viral-genome-tree/__tests__/viral-genome-tree-form-utils.test.ts:16-26], [src/app/services/(phylogenomics)/gene-protein-tree/page.tsx:556-590]

Alignment Parameters

The pipeline includes steps for refining the multiple sequence alignment before tree construction.

Parameter	Description
Trim ends threshold	Sets the threshold for trimming ends of the alignment to remove low-quality extremities.
Remove gappy sequences	Sets the threshold for removing sequences with excessive gaps at alignment extremities.

Sources: [src/lib/services/service-info.ts:586-595], [src/app/services/(phylogenomics)/gene-protein-tree/page.tsx:430-460]

Summary

The Phylogenomics Tools Integration provides a robust framework for evolutionary analysis within the DXKB platform. By combining user-friendly sequence selection with rigorous validation and high-performance maximum likelihood algorithms, it enables researchers to derive evolutionarily accurate relationships from genomic and proteomic data. All analysis jobs are managed through a standardized submission process that outputs visualization-ready Newick files to the user's workspace.

Sources: [src/lib/services/service-info.ts:543-556], [src/app/services/(phylogenomics)/gene-protein-tree/page.tsx:135-150]