evolutionary-tree-analyzer 1.1.0

Build and visualize phylogenetic trees from FASTA files using parsimony and ML-style methods.

🌿 SimplePhylo

A phylogenetic tree builder for DNA sequence analysis using parsimony and maximum likelihood methods.

Why it matters:

• 🔍 Parsimony finds the simplest tree with the fewest evolutionary changes—lightning-fast and perfect for classroom demos or sketching out relationships in agricultural genetics.

• 🧮 Maximum Likelihood applies explicit statistical models of sequence evolution to infer the tree that best explains your data—essential for robust analyses in real-world forensics or crop-breeding studies.

• ⚖️ Compare both to gauge confidence, uncover hidden rate variation, and get a fuller picture of evolutionary history.

  Whether you’re teaching high school biology or delving into forensic DNA casework, SimplePhylo empowers you to explore and explain phylogenies with clarity and rigor.

---

📋 Table of Contents

1. Overview
2. 🚀 Quick Start
3. 📁 Project Structure
4. 📦 Dependencies
5. ⚙️ MUSCLE Alignment Notes
6. 🧪 Example Workflow
7. 📅 Future Plans
8. 🧰 Maintainer
9. 📄 License
10. 📜 Citations & Attributions

---

🧐 Overview

SimplePhylo (a.k.a. Evolutionary Tree Analyzer) is a cute, flash‑fast Python package and Dash web app for building phylogenetic trees from FASTA sequences.

It enables you to:

• Parse DNA sequences in FASTA format.
• Align them using MUSCLE v3.8.31.
• Build phylogenetic trees via both Parsimony (UPGMA) and ML-style (distance-based on identity).
• Visualize and export tree images as .png for teaching slides, lab reports, or research.

Whether you’re running a quick classroom demo or prototyping a research pipeline, SimplePhylo keeps everything modular and accessible.

---

🚀 Quick Start

1. Clone the repo

git clone https://github.com/YourUser/evolutionary-tree-analyzer.git  
cd evolutionary-tree-analyzer  

2. Install dependencies

(pick one)

# From PyPI (stable release)
pip install evolutionary-tree-analyzer  

# From GitHub (editable/dev mode)
pip install -r requirements.txt  
pip install -e .

3. Launch the Dash App

python main.py

4. (Totally optional) Run the notebook

jupyter notebook notebooks/tree_builder.ipynb

❓ Questions? Drop me a line at [e-mail]

---

📁 Project Structure

evolutionary-tree-analyzer/
|
├── .github/                 # CI workflows and configuration
│   └── workflows/           # GitHub Actions for testing, packaging
│       └── ci.yml           # Continuous integration pipeline
|
├── assets/                  # Pipeline Bio logos (sunflower + tree)
|
├── bin/                     # MUSCLE binary (v3.8.31) with +x permission
|
├── data/                    # Example FASTA inputs
│   ├── vertebrate_test.fa   # Small demo FASTA with vertebrate mitochondrion seqs
│   └── example_small.fa     # Small FASTA sample for testing
|
├── notebooks/               # Jupyter workflow (tree_builder.ipynb)
|
├── output/                  # Generated alignments and tree images
│   └── tree_images/         # Parsimony & ML PNG outputs
|
├── src/                     # Core Python library modules
│   ├── fasta_parser.py      # Parse FASTA → SeqIO records
│   ├── align_sequences.py   # Run MUSCLE alignment
│   ├── build_tree.py        # Build parsimony & ML-style trees
│   └── visualize_tree.py    # Render trees to PNG via Biopython Phylo
|
├── tests/                   # pytest test suite for modules
│   └── test_align_sequences.py
│   ├── test_fasta_parser.py      
│   ├── test_build_tree.py        
│   └── test_visualize_tree.py    
|
├── handle_upload.py         # Utility for file ingestion
├── main.py                  # Dash web-app entrypoint
├── render.yaml              # Deployment config for Render.com
├── requirements.txt         # Runtime dependencies
├── setup.py                 # Packaging metadata for PyPI
├── CHANGELOG.md             # Release notes
├── LICENSE                  # MIT License
└── README.md                # Project overview and usage

---

📦 Dependencies

Python ≥3.8 and the following PyPI packages:

• dash & dash-bootstrap-components – build the interactive web UI
• biopython – FASTA parsing, tree building & Phylo rendering
• matplotlib – save publication-quality tree images
• scipy – compute distance matrices for ML-style trees
• click – simple command-line interface (CLI)

Standard library

• subprocess, os, pathlib – invoke & locate external tools
• importlib.util – dynamic module loading in notebooks
• logging – configurable console output

---

⚙️ MUSCLE Alignment Notes

This project uses MUSCLE v3.8.31 to align DNA sequences.

• For small files, alignment runs automatically in Python
• For large files, use the batch script: align_manual.bat

You must have MUSCLE installed and accessible from your system's PATH for alignment.

💡 Ensure the muscle.exe binary is placed in: C:\Program Files\muscle\muscle.exe Or edit the .bat file to reflect the correct path.

MUSCLE citation: Edgar, R.C. (2004) Nucleic Acids Res 32(5):1792–1797. http://www.drive5.com/muscle

✨Please cite this work if you use the alignment functionality in your research or publications.

🧠 Tips for Large Input Files

• Work smaller first: debug your pipeline on 5–10 sequences before scaling up.
• Split & conquer: break multi-FASTA into chunks (seqkit split2 or bash loops).
• Memory guardrails: MUSCLE can spike RAM on huge alignments—keep input FASTA under 50 MB.
• Use the batch script (align_manual.bat or your own shell wrapper) for > 1000 sequences.

---

🧪 Example Workflow

1. Drop your .fasta file into the data/ folder
2. Launch the app or notebook
3. You’ll get:

• A multiple sequence alignment (FASTA)
• Two phylogenetic trees (Parsimony & ML-style)
• PNG files saved in output/tree_images/

Perfect for: 🧬 Biology class demonstrations 🧪 Research prototyping 📚 Curriculum development 💡 Student-led investigations

---

🧰 Future Plans

• Add support for bootstrap analysis
• Export PDF/HTML reports
• Add tree comparison metrics (e.g., RF distance) Want to see SimplePhylo improved? I welcome all feedback and I can't wait to hear from you!

---

👩‍💻 Maintainer

Pipeline Bio – Simple Bioinformatics for Educators
🌻 Sunflower logo with a phylogenetic tree
📫 Contact: [e-mail]
🛒 Teachers Pay Teachers Store: Pipeline Bio
📌 #teacherspayteachers

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.

---

🧾 Citations & Attributions

This project uses the MUSCLE alignment tool developed by Robert C. Edgar.

Edgar, R.C. (2004) MUSCLE: multiple sequence alignment with high accuracy and high throughput. Nucleic Acids Research, 32(5):1792–1797.
http://www.drive5.com/muscle

Please cite this work if you use the alignment functionality in your research or publications.

---

🧬 Happy tree building! © 2025 Mae Warner (Pipeline Bio). All rights reserved.