Biological Entity Viewers

Relevant source files

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

• public/js/p3/widget/TaxonomyOverview.js
• public/js/p3/widget/GenomeOverview.js
• public/js/p3/widget/FeatureOverview.js
• public/js/p3/widget/viewer/PhylogeneticTree.js
• public/js/p3/widget/BacteriaOverview.js
• public/js/p3/widget/VirusOverview.js
• public/js/p3/widget/templates/TaxonomyOverview.html
• public/js/p3/widget/templates/GenomeOverview.html

Biological Entity Viewers are specialized UI components designed to provide comprehensive summaries and interactive visualizations for different levels of biological data, including Taxonomies, Genomes, and individual Genomic Features. These viewers act as central hubs for data exploration, aggregating metadata, functional properties, and external references into a unified interface.

The system utilizes a modular architecture based on the Dojo toolkit, where specific overview widgets (e.g., GenomeOverview, TaxonomyOverview) manage state, fetch data from the Data API, and delegate specialized rendering to sub-widgets like GenomeFeatureSummary or Phylogeny viewers.

Sources: public/js/p3/widget/TaxonomyOverview.js, public/js/p3/widget/GenomeOverview.js, public/js/p3/widget/FeatureOverview.js

Taxonomy Viewers

Taxonomy viewers provide a high-level summary of biological data at specific taxonomic ranks. They are specialized into context-specific implementations for Bacteria and Viruses, though they share a common base class structure.

Architecture and Data Flow

The TaxonomyOverview widget serves as the primary entry point. When the state is updated with a taxon_id, the widget triggers asynchronous requests to the Data API to fetch summary data and refreshes internal summary widgets.

Key features of the taxonomy view include:

• Taxonomy Summary: Aggregated data formatted via DataItemFormatter using the taxonomy_overview_data template.
• Genomes by Metadata: Visualization of genomes within the taxon based on key metadata attributes.
• External Links: Dynamic generation of links to external resources such as BEI Resources and PubMed based on the taxon name.

Sources: public/js/p3/widget/TaxonomyOverview.js:34-75, public/js/p3/widget/templates/TaxonomyOverview.html

Context-Specific Overview Widgets

The system differentiates between bacterial and viral taxa through specialized overview widgets:

Widget	Purpose	Key Sub-widget
BacteriaOverview	Summary for bacterial taxa.	BacteriaMetaSummary
VirusOverview	Summary for viral taxa.	VirusMetaSummary

Sources: public/js/p3/widget/BacteriaOverview.js, public/js/p3/widget/VirusOverview.js

Genome Viewer

The GenomeOverview widget provides a detailed look at a specific genome. It is context-sensitive, adjusting its UI components based on whether the genome is classified as a virus or bacteria.

Genome Data Presentation

The viewer aggregates several data categories:

1. Antimicrobial Resistance (AMR): Displays AST data via the AMRPanelSummary (primarily for bacteria).
2. Genomic Features: Summarizes features annotated by the system and GenBank/RefSeq.
3. Protein Features: Summarizes functional attributes and protein family assignments.
4. Specialty Genes: Highlights genes of interest like virulence factors and drug targets.

Context Logic

The UI dynamically hides or shows components based on the context attribute:

• Bacteria Context: Displays Protein Family and Specialty Gene summary widgets.
• Virus Context: Hides Protein Family and Specialty Gene summary widgets.

Sources: public/js/p3/widget/GenomeOverview.js:32-75, public/js/p3/widget/templates/GenomeOverview.html

Genome Action Suite

Genomes have associated actions accessible via the UI:

• Download: Opens a DownloadTooltipDialog for data retrieval.
• Share: Launches a PermissionEditor if the user owns the genome.
• Add to Group: Uses SelectionToGroup to organize genomes into user-defined sets.
• Metadata Editing: Users owning the genome can launch a MetaEditor to update genome metadata.

Sources: public/js/p3/widget/GenomeOverview.js:101-140, 201-260

Feature Viewer

The FeatureOverview widget handles individual genomic features (genes, proteins). It provides deep integration with functional databases and sequence visualization.

Functional Properties and Annotation

The viewer fetches and displays multiple annotation types:

• Protein Families: Links to PLfam, PGfam, and FIGfam IDs.
• Pathways and EC Numbers: Aggregates KEGG pathway IDs and Enzyme Commission descriptions.
• Subsystems: Lists role names and subsystem categories associated with the feature.
• GO Terms: Provides direct links to the Gene Ontology (AmiGO) database.

Sources: public/js/p3/widget/FeatureOverview.js:203-270

Sequence and Structure Visualization

D3 Single Gene Viewer:* Renders a linear map of the feature and its immediate neighbors on the contig.

• Structure Requests: For specific genera (e.g., Mycobacterium, Bacillus), the viewer provides buttons to submit structure determination requests to SSGCID or CSGID.

Sources: public/js/p3/widget/FeatureOverview.js:460-500, 316-360

Phylogenetic Tree Viewer

The PhylogeneticTree viewer manages the visualization of evolutionary relationships. It primarily interfaces with the Workspace Manager to retrieve Newick (.nwk) or PhyloXML files.

Configuration Element	Description
idType	Determines the ID used for nodes (default: genome_id).
labelType	Determines the display label for nodes (default: genome_name).
wsTreeFolder	Workspace path to a folder containing tree data files.
labelSearch	Boolean flag to trigger an API lookup for metadata labels.

Sources: public/js/p3/widget/viewer/PhylogeneticTree.js:100-140

Label Resolution Logic

If labelSearch is enabled, the viewer extracts IDs from the Newick string and performs a POST request to the API to fetch corresponding names:

1. Extract IDs using regex /[^(,)]+(?=:)/g.
2. Filter for valid IDs (containing dots).
3. Query the genome endpoint for the labelType field.
4. Map IDs to names and pass the resulting label object to the Phylogeny rendering engine.

Sources: public/js/p3/widget/viewer/PhylogeneticTree.js:180-230

Conclusion

Biological Entity Viewers provide a structured, hierarchy-aware interface for exploring complex omics data. By utilizing context-sensitive widgets and standardized data formatters, the system ensures that relevant biological information—from taxonomic distributions to specific protein interactions—is consistently accessible to the researcher.

Sources: public/js/p3/widget/TaxonomyOverview.js, public/js/p3/widget/GenomeOverview.js, public/js/p3/widget/FeatureOverview.js