How cami-challenge/amber works
Project Type and Purpose
• AMBER is a command-line driven, Python-based evaluation package for metagenome binning results. It ingests gold-standard and predicted binning files, computes performance metrics, generates comparative rankings and visualizations, and produces standalone HTML reports. The packaging supports installation via pip, Bioconda, and Docker, with CI (CircleCI) and testing (tox, BDD features) workflows.
File-Structure Analysis
• Top-level artifacts:
• Dockerfile, .circleci/config.yml, tox.ini, setup.py, setup.cfg, requirements.txt, README.md, LICENSE
• amber.py (CLI entrypoint)
• cami_amber/ (core Python package)
• cami_amber/utils/ (utility scripts)
• cami_i_hc/, cami_ii_mouse_gut/, cami_ii_mouse_gut_filter1/ (example HTML output directories)
• features/ (BDD tests using behave)
• test/ (unit/integration test data)
• Patterns:
• Layered: CLI → Core modules → Utilities → Reporting/HTML
• Modular: evaluation, plotting, HTML generation in separate modules
• Plugin-style utils for supporting formats (e.g. add_length, convert_fasta)
Key README Insights
• Describes metrics computed per bin and per sample
• Details inputs: gold standard in Biobox TSV, predicted bins, optional NCBI taxonomy dump
• Outlines usage of amber.py CLI with flags
• Documents utility scripts under cami_amber/utils
• Explains installation, Docker usage, testing (tox), and publishing workflows
Main Components
a. Frontend → the CLI “amber.py” (user interface)
b. Core Engine (package “cami_amber”):
• Data loaders (utils/load_data, load_ncbi_taxinfo)
• Evaluation modules (evaluate.py, precision_recall_per_bin.py, unifrac_distance.py)
• Plotting modules (plots.py, plot_by_genome.py, amber_html.py)
• Binning-specific logic (binning_classes.py)
c. Utility Scripts (cami_amber/utils/*): add_length_column, convert_fasta_bins_to_biobox_format, profiling tools, argument parsers
d. Output Layer:
• TSV summaries, metrics files
• HTML reports (index.html, example pages under cami_i_hc/, cami_ii_mouse_gut/)
e. External Services/Artifacts:
• Gold-standard and predicted binning TSV files (input)
• NCBI taxonomy dump (nodes.dmp) for taxonomic binning
• Docker container registry, PyPI, Bioconda (deployment targets)
• CI/CD pipeline (CircleCI), Test harness (tox, behave features)
Relationships and Data Flow
• User invokes amber.py with input files → CLI parses arguments and calls core engine
• Core engine loads mappings via utils → evaluation modules compute metrics
• Plotting modules generate charts; HTML generator stitches charts and metrics into reports
• Outputs written to OUTPUT_DIR (TSV + HTML pages)
• Utility scripts invoked standalone or by core engine as needed
• CI pipeline builds Docker, runs tox/behave, deploys artifacts
Architectural Patterns and Principles
• Separation of concerns: UI, data ingestion, metric computation, visualization, output
• Modular Python package structure for maintainability
• Reusable utilities for format conversions and profiling
• Clear layering: presentation (HTML), service (evaluation), data (IO)
Technologies and Frameworks
• Python 3.11, setuptools for packaging
• Matplotlib/Seaborn or similar for plotting (implicit via plots.py)
• behave/pytest for BDD and unit tests
• Docker for containerization
• CircleCI for CI/CD, tox for environment management
• Bioconda and PyPI for distribution