# cami-challenge/amber architecture

> Architecture diagram of the GitHub repository cami-challenge/amber, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cami-challenge/amber
- Repository: https://github.com/cami-challenge/amber

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface"
        amber["amber.py"]:::ui
    end

    subgraph "External Inputs"
        gold["Gold-standard TSV"]:::storage
        pred["Predicted bins TSV"]:::storage
        ncbi["NCBI taxonomy dump"]:::storage
    end

    amber -->|"args"| gold
    amber -->|"args"| pred
    amber -->|"args"| ncbi

    subgraph "Core Engine"
        subgraph "Data Loaders"
            ld1["load_data.py"]:::core
            ld2["load_ncbi_taxinfo.py"]:::core
        end
        subgraph "Evaluation Modules"
            ev1["evaluate.py"]:::core
            ev2["precision_recall_per_bin.py"]:::core
            ev3["unifrac_distance.py"]:::core
        end
        subgraph "Binning Logic"
            bin["binning_classes.py"]:::core
        end
        subgraph "Plotting & HTML"
            plt1["plots.py"]:::core
            plt2["plot_by_genome.py"]:::core
            html["amber_html.py"]:::core
        end
    end

    amber -->|"calls"| ld1
    amber -->|"calls"| ld2
    ld1 -->|"provides Data"| ev1
    ld1 -->|"provides Data"| ev2
    ld2 -->|"provides Taxonomy"| ev3
    ev1 -->|"metrics"| plt1
    ev2 -->|"metrics"| plt1
    ev3 -->|"metrics"| plt1
    plt1 -->|"plots"| plt2
    plt2 -->|"figures"| html

    subgraph "Output Layer"
        outTSV["TSV Summaries"]:::storage
        outHTML["HTML Reports"]:::storage
    end

    html -->|"generates"| outTSV
    html -->|"generates"| outHTML

    subgraph "Utilities"
        ul1["add_length_column.py"]:::utils
        ul2["convert_fasta_bins_to_biobox_format.py"]:::utils
        ul3["ProfilingTools.py"]:::utils
        ul4["EMDUnifrac.py"]:::utils
        ul5["argparse_parents.py"]:::utils
        ul6["labels.py"]:::utils
    end

    amber -->|"utilizes"| ul1
    amber -->|"utilizes"| ul2
    ev3 -->|"uses"| ul4

    subgraph "CI/CD & Deployment"
        pkg["setup.py"]:::deploy
        docker["Dockerfile"]:::deploy
        circle[".circleci/config.yml"]:::deploy
        tox["tox.ini"]:::deploy
        req["requirements.txt"]:::deploy
    end

    circle -->|"runs"| pkg
    circle -->|"runs"| tox
    docker -->|"builds"| pkg

    subgraph "Testing"
        test["test/"]:::deploy
        feat["features/"]:::deploy
    end

    circle -->|"executes"| test
    circle -->|"executes"| feat

    click amber "https://github.com/cami-challenge/amber/blob/master/amber.py"
    click ld1 "https://github.com/cami-challenge/amber/blob/master/cami_amber/utils/load_data.py"
    click ld2 "https://github.com/cami-challenge/amber/blob/master/cami_amber/utils/load_ncbi_taxinfo.py"
    click ev1 "https://github.com/cami-challenge/amber/blob/master/cami_amber/evaluate.py"
    click ev2 "https://github.com/cami-challenge/amber/blob/master/cami_amber/precision_recall_per_bin.py"
    click ev3 "https://github.com/cami-challenge/amber/blob/master/cami_amber/unifrac_distance.py"
    click plt1 "https://github.com/cami-challenge/amber/blob/master/cami_amber/plots.py"
    click plt2 "https://github.com/cami-challenge/amber/blob/master/cami_amber/plot_by_genome.py"
    click html "https://github.com/cami-challenge/amber/blob/master/cami_amber/amber_html.py"
    click bin "https://github.com/cami-challenge/amber/blob/master/cami_amber/binning_classes.py"
    click ul1 "https://github.com/cami-challenge/amber/blob/master/cami_amber/utils/add_length_column.py"
    click ul2 "https://github.com/cami-challenge/amber/blob/master/cami_amber/utils/convert_fasta_bins_to_biobox_format.py"
    click ul3 "https://github.com/cami-challenge/amber/blob/master/cami_amber/utils/ProfilingTools.py"
    click ul4 "https://github.com/cami-challenge/amber/blob/master/cami_amber/utils/EMDUnifrac.py"
    click ul5 "https://github.com/cami-challenge/amber/blob/master/cami_amber/utils/argparse_parents.py"
    click ul6 "https://github.com/cami-challenge/amber/blob/master/cami_amber/utils/labels.py"
    click outHTML "https://github.com/cami-challenge/amber/blob/master/cami_i_hc/index.html"
    click pkg "https://github.com/cami-challenge/amber/blob/master/setup.py"
    click docker "https://github.com/cami-challenge/amber/tree/master/Dockerfile"
    click circle "https://github.com/cami-challenge/amber/blob/master/.circleci/config.yml"
    click tox "https://github.com/cami-challenge/amber/blob/master/tox.ini"
    click req "https://github.com/cami-challenge/amber/blob/master/requirements.txt"
    click test "https://github.com/cami-challenge/amber/tree/master/test/"
    click feat "https://github.com/cami-challenge/amber/tree/master/features/"

    classDef ui fill:#cfe2f3,stroke:#6fa8dc
    classDef core fill:#d9ead3,stroke:#93c47d
    classDef utils fill:#f9cb9c,stroke:#e69138
    classDef storage fill:#e7e7e7,stroke:#aaa
    classDef deploy fill:#d9d2e9,stroke:#8e7cc3
```
