How mmcguffi/plannotate works
Project type and purpose
• pLannotate is a full-stack bioinformatics application:
• Backend “annotation engine” (Python modules that parse input FASTA/GenBank, run searches, assemble annotation results)
• Two presentation layers:
– Command-Line Interface (CLI) for batch annotation
– Streamlit‐based local web server for interactive use
• Data layer of built-in reference databases (CSV, FASTA, YAML) and HTML templates
File structure
• Top‐level:
• plannotate/ — core Python package
• .streamlit/ — Streamlit config
• environment.yml, requirements.txt, setup.py — dependency and packaging
• tests/ — unit and manual tests
• .github/workflows/ — CI pipelines
• plannotate/ submodules:
• .py — core annotation logic (search engines, filtering)
• infernal.py — wrappers around external search tools (e.g., Infernal)
• resources.py — loading and caching of sequence-record utilities
• bokeh_plot.py — transforms annotation results into interactive Bokeh figures
• streamlit_app.py — Streamlit server (UI/controller)
• pLannotate.py — CLI entry points (batch, setupdb, yaml dump)
• data/ — static assets:
– data/data/*.csv, .yml — built-in feature/type databases
– data/fastas/ — reference sequences
– data/templates/ — HTML snippets for web output
• Config & packaging:
• setup.py & environment.yml define installation and conda environment
• tox.ini, .github/workflows drive testing matrix
Extract architectural insights from README
• Two usage modes: plannotate batch (CLI) and plannotate streamlit (web UI)
• Data flow: input sequence → annotation engine → get_seq_record → get_bokeh → HTML/GBK/CSV outputs or live plot
• Customizability: users can supply YAML to point at external databases
Main components & interactions
A. Presentation layer
1. CLI Module (pLannotate.py)
2. Streamlit App (streamlit_app.py)
3. Bokeh Plot Renderer (bokeh_plot.py + templates)
B. Core Logic layer
1. Annotation Engine (annotate.py)
2. Search Wrappers (infernal.py, plus any BLAST/HMMER calls)
3. Resource Loader (resources.py)
C. Data layer
1. Built-in Databases (CSV/YAML under data/data/)
2. Reference FASTA sequences (data/fastas/)
3. HTML Templates (data/templates/)
D. Configuration & Infrastructure
1. Conda Environment (environment.yml)
2. Package Metadata (setup.py, requirements.txt)
3. CI/CD (tox.ini, GitHub workflows)
E. External Dependencies
1. Python 3 runtime
2. Streamlit framework
3. Bokeh visualization library
4. BioPython for SeqRecord
5. External search tools (Infernal/HMMER) invoked via infernal.py
Relationships & data flows
• User invokes CLI or opens the Streamlit web page
→ CLI/Streamlit processes input sequence
→ Calls Annotation Engine
→ Engine uses Resource Loader to fetch reference databases & templates
→ Engine calls Search Wrappers (infernal.py) to perform sequence searches
→ Collects “hits” and assembles annotation results
→ Passes results to Bokeh Plot Renderer
→ Generates interactive HTML (for web) or standalone HTML/CSV/GBK files (for CLI)
• Configuration (YAML, environment.yml) influences Resource Loader and Search Wrappers
Architectural patterns & design principles
• “Separation of Concerns”:
• Clear layering: Presentation (UI) vs. Core Logic vs. Data
• Modular design:
• Each Python module has a single responsibility (annotate, plot, CLI, resources)
• Extensibility:
• Databases defined in YAML; new data sources or search tools can be added without changing core logic
• Reusability:
• Core annotation logic is decoupled from the UI, so it can be imported as a Python module