{"id":"3df91ecb-0848-432b-ba4f-8109d23a8d6f","slug":"x-amplicon","kind":"skill","name":"X--Amplicon","summary":"X-Amplicon is a Python workflow and AI Agent designed for 16S rRNA amplicon paired-end sequencing data.","owner":"xuxinxi14","repoUrl":"https://github.com/xuxinxi14/X--Amplicon","license":"GPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":3,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-04-26T15:49:38.000Z","addedAt":"2026-10-22T00:57:04.989Z","logoUrl":"https://avatars.githubusercontent.com/u/225154917?u=5ab68d08d431547c151a3a8fd1c03a270c9eecbf&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["data-analytics"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T00:09:02.702Z","sample":false,"url":"https://conduits.dev/tools/x-amplicon","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"[English](README.md) | [δΈ­ζ–‡](README_zh.md)\n\n# 🧬 X-Amplicon\n**Author:** XinXi Xu\n\nX-Amplicon is a Windows-first local Agent and Web UI for 16S rRNA amplicon analysis, with a Linux x86_64 server package for command-line and browser-based deployment. It turns paired-end FASTQ files and a metadata table into OTU/ASV tables, taxonomy annotation, alpha/beta diversity, publication-ready visualizations, differential abundance plots, reports, and reproducibility records.\n\n> πŸ’‘ **Recommended workflow:** Use the local browser Web UI. Your sequencing files never leave your computer, the wizard guides you step by step, and everything runs through the same deterministic Python workflow as the CLI. An LLM API key is entirely optional.\n\n## ✨ Highlights\n\n- Local Windows Web UI for wet-lab users.\n- One-click Windows installer with bundled Python, RDP 16S database, USEARCH/VSEARCH, and prebuilt Web UI.\n- Linux x86_64 package with setup, Web UI, CLI launchers, bundled small RDP database, and server test workflow.\n- Guided Agent page for analysis readiness and step-by-step execution.\n- Deterministic `process.py` workflow for reproducibility and automation.\n- No-LLM mode for local checks, visualization, reports, and most guidance.\n- Optional LLM configuration from the Web UI: API key, API base URL, and model selection.\n- Outputs include Plotly charts, report HTML/Markdown, `run_summary.json`, and provenance files.\n\n\"c1a4c08be4838b85f1ee997ea8b795b\"\n\n\n## πŸš€ Quick Start: Windows Installer\n\nThe easiest way to get started is to download the Windows installer directly from GitHub Releases:\n\n```text\nX-Amplicon-Setup-v0.1.2.exe\n```\n\nThen:\n\n1. Double-click `X-Amplicon-Setup-v0.1.2.exe` to launch the setup wizard.\n2. Follow the prompts. The default per-user install path is:\n\n```text\n%LOCALAPPDATA%\\Programs\\X-Amplicon\n```\n\n3. Launch **X-Amplicon Web UI** from the Start Menu or desktop shortcut β€” and you're ready to analyze!\n\nThe normal shortcut starts X-Amplicon without showing a terminal window. A small startup window shows progress until the backend is ready, then the Web UI opens. Closing the Web UI app window also stops the local backend. The visible `Start_X-Amplicon_WebUI.cmd` launcher is still included for troubleshooting.\n\nThe launcher automatically verifies the bundled Python environment and RDP database, then opens the local Web UI. The default address is:\n\n```text\nhttp://127.0.0.1:8765\n```\n\nIf the hidden launcher fails, run `Start_X-Amplicon_WebUI.cmd` from the installation folder to see startup messages.\n\n### πŸ“¦ What the Installer Includes\n\n| Component | Installed path |\n| --- | --- |\n| Bundled Python runtime | `.tools\\python-3.13.13-amd64\\python.exe` |\n| Small 16S database | `database\\rdp_16s_v18.fa` |\n| USEARCH/VSEARCH executables | `bin\\windows\\` |\n| X-Amplicon core workflow | `process.py`, `src\\`, `agent\\` |\n| Web UI backend | `webui\\backend\\` |\n| Prebuilt Web UI frontend | `webui\\frontend\\dist\\` |\n| One-click launchers | `Start_X-Amplicon_WebUI.vbs`, `Start_X-Amplicon_WebUI.cmd`, `Start_X-Amplicon_WebUI.ps1` |\n\nThe installer does not include user FASTQ data, analysis outputs, API keys, runtime state, `node_modules`, or large SILVA databases β€” all that stays yours.\n\n## πŸ› οΈ Quick Start: Source Checkout\n\nPrefer working from source? Install the dependencies first:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\setup_windows.ps1 -InstallWebUIDeps\n```\n\nIf PyPI is slow in your region, use the China mirror:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\setup_windows.ps1 -UseChinaMirror -InstallWebUIDeps\n```\n\nStart the Web UI:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\start_webui.ps1\n```\n\nHandy startup flags (change port or suppress auto-open):\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\start_webui.ps1 -Port 8770\npowershell -ExecutionPolicy Bypass -File .\\start_webui.ps1 -NoBrowser\n```\n\n## Quick Start: Linux x86_64 Server\n\nThe Linux release workspace is intended for Ubuntu 22.04 x86_64 or compatible x86_64 Linux servers:\n\n```bash\ncd /path/to/X-Amplicon_linux_x86_64\nchmod +x setup_linux.sh start_webui.sh run_process.sh run_agent.sh\n./setup_linux.sh --china-mirror\n```\n\nCheck external tools and pipeline configuration:\n\n```bash\n./bin/usearch --version\n./bin/vsearch --version\n./run_process.sh check-pipeline-config --params pipeline_params.linux.yaml\n```\n\nRun the full CLI workflow:\n\n```bash\n./run_process.sh run-pipeline-config --params pipeline_params.linux.yaml\n./run_process.sh visualization-suite --final-dir work/06_final --format html\n./run_process.sh generate-report --final-dir work/06_final\n```\n\nStart the Linux Web UI from a terminal, not by clicking the `.sh` file in Jupyter:\n\n```bash\n./start_webui.sh --no-browser\n```\n\nOn an SSH server, forward the Web UI to your local browser:\n\n```bash\nssh -N -L 8765:127.0.0.1:8765 user@server\n```\n\nThen open `http://127.0.0.1:8765`.\n\nFor offline report browsing over SSH, serve the result directory through a local-only HTTP server:\n\n```bash\n.venv/bin/python -m http.server 8899 --bind 127.0.0.1\nssh -N -L 8899:127.0.0.1:8899 user@server\n```\n\nThen open `http://127.0.0.1:8899/work/06_final/report/analysis_report.html`.\n\n## Web UI Workflow\n\nFollow these steps in order for a smooth analysis experience:\n\n1. **Settings**: confirm your Python path, output directory, metadata path, FASTQ directory, USEARCH/VSEARCH paths, plot format, and any optional LLM settings.\n2. **Agent**: work through the guided readiness checklist to make sure everything is in order before kicking off the analysis.\n3. **New Analysis**: create a project, select your metadata and paired FASTQ files, validate sample matching, choose groups, define comparisons, and set parameters.\n4. **Run Monitor**: run preflight checks, launch the full pipeline, watch the live logs, and grab the reproducible commands for your records.\n5. **Results**: explore plots, tables, differential abundance results, reports, provenance files, and all outputs at a glance.\n6. **Databases**: inspect the bundled RDP database or register your own custom FASTA database.\n\nThe Web UI never uploads your sequencing files. All data, logs, and results stay on your machine.\n\n## πŸ“‚ Input Files\n\"image\"\n\nA typical project layout looks like this:\n\n```text\nyour_project\\\n metadata.txt\n seq\\\n S1_1.fq.gz\n S1_2.fq.gz\n S2_1.fq.gz\n S2_2.fq.gz\n```\n\nMinimal metadata:\n\n```text\nSampleID\tGroup\nS1\tWT\nS2\tKO\n```\n\nFormat requirements:\n\n- Metadata must be a tab-separated text file (TSV).\n- Sample IDs must match paired FASTQ filenames after stripping the R1/R2 suffixes.\n- A group column such as `Group` is required for diversity plots and differential comparisons.\n\n## πŸ“Š Output Files\n\"image\"\n\nThe default output root is:\n\n```text\nwork\\\n```\n\nFinal results are written to:\n\n```text\nwork\\06_final\n```\n\nMain outputs:\n\n| Output | Default location |\n| --- | --- |\n| OTU/ASV table | `work\\06_final\\otutab.txt` |\n| Taxonomy annotation | `work\\06_final\\otus.sintax`, `work\\06_final\\taxonomy.tsv` |\n| Alpha diversity | `work\\06_final\\alpha\\alpha_diversity.tsv` |\n| Beta diversity | `work\\06_final\\beta\\` |\n| Visualization browser | `work\\06_final\\plots\\index.html` |\n| Differential abundance | `work\\06_final\\differential_abundance\\` |\n| Report | `work\\06_final\\report\\analysis_report.html` |\n| Reproducibility records | `work\\06_final\\run_summary.json`, `provenance.json`, `provenance.md` |\n\nThe CLI `run-pipeline-config` command writes the core analysis outputs first.\nGenerate `plots/` and `report/` afterward with `visualization-suite` and\n`generate-report`. Plot outputs are organized in subfolders instead of being\nplaced together in one directory.\n\n## πŸ€– Optional LLM Agent\n\"image\"\n\nThe full analysis workflow runs perfectly without an API key. To unlock LLM-assisted guidance, follow these steps:\n\n1. Open **Settings** in the Web UI.\n2. Select or type a LiteLLM-compatible model name.\n3. Enter an OpenAI-compatible API base URL if you're using a proxy or custom gateway.\n4. Enter your API key and save.\n\nYour key is saved locally to `.env` and is never sent back to the browser by the settings API β€” it stays safely on your machine.\n\nEquivalent `.env` fields:\n\n```text\nDEFAULT_MODEL=gpt-4o-mini\nLLM_API_KEY=your_key_here\nLLM_API_BASE=https://your-openai-compatible-endpoint/v1\n```\n\n## ⌨️ CLI Usage\n\nThe Web UI is recommended for most users. The CLI is there when you need scripted, reproducible runs or automation.\n\nRun the standard workflow:\n\n```powershell\npython process.py check-pipeline-config --params pipeline_params.yaml\npython process.py run-pipeline-config --params pipeline_params.yaml\npython process.py visualization-suite --final-dir work\\06_final --format html\npython process.py differential-abundance --reference-group WT --format html\npython process.py generate-report --final-dir work\\06_final\n```\n\nUseful CLI tools:\n\n| Task | Command |\n| --- | --- |\n| Validate configuration | `python process.py check-pipeline-config --params pipeline_params.yaml` |\n| Run full pipeline | `python process.py run-pipeline-config --params pipeline_params.yaml` |\n| Generate visualizations | `python process.py visualization-suite --final-dir work\\06_final --format html` |\n| Run differential abundance | `python process.py differential-abundance --reference-group WT --format html` |\n| Generate report | `python process.py generate-report --final-dir work\\06_final` |\n| Check database | `python process.py check-database rdp_16s_v18` |\n| List all CLI commands | `python process.py --help` |\n\nCLI Agent:\n\n```powershell\npython agent_cli.py\npython agent_cli.py --offline\n```\n\nUseful slash commands include `/params`, `/status`, `/tools`, `/language`, `/report`, `/config`, and `/quit`. Type `/help` at any time for the full list.\n\n## Linux Packaging Options\n\nLinux does not use Windows `.exe` installers in the same way. The closest options are:\n\n| Option | When to use | Notes |\n| --- | --- | --- |\n| Portable `tar.gz` release | Recommended for servers and clusters | Ship the project directory, run `setup_linux.sh` on the target machine, and start with shell launchers. |\n| AppImage | Closest double-click desktop experience | Produces one Linux application file, but needs extra packaging work and testing per distribution. |\n| PyInstaller/Nuitka executable | CLI or launcher binary | Can produce an ELF executable, but Web UI assets, database files, and USEARCH/VSEARCH still need to be bundled or placed beside it. |\n| `.deb` package | Managed Ubuntu deployment | Best for internal IT deployment, but requires Debian packaging metadata and install scripts. |\n\nFor this project, the most reliable Linux equivalent of the Windows installer is a portable directory archive:\n\n```bash\ncd ..\ntar --exclude='X-Amplicon_linux_x86_64/.venv' \\\n --exclude='X-Amplicon_linux_x86_64/work' \\\n --exclude='X-Amplicon_linux_x86_64/seq' \\\n --exclude='X-Amplicon_linux_x86_64/.env' \\\n -czf X-Amplicon_linux_x86_64.tar.gz X-Amplicon_linux_x86_64\n```\n\nUsers unpack it, run `./setup_linux.sh`, then launch `./start_webui.sh --no-browser` or `./run_process.sh ...`. Build PyInstaller/AppImage artifacts only on a Linux system compatible with the target servers, and check redistribution terms for external tools such as USEARCH before bundling them.\n\n## Dependencies\n\nThe Windows installer already includes everything needed for ordinary use. If you're building from source, install the following:\n\n| Category | Packages or tools |\n| --- | --- |\n| Core Python | `numpy`, `pandas`, `scipy`, `scikit-bio`, `pyyaml`, `click`, `biopython`, `pydantic`, `plotly`, `rich`, `litellm` |\n| Web UI backend | `fastapi`, `uvicorn[standard]`, `python-multipart`, `aiofiles` |\n| Static plot export | `kaleido` |\n| Optional Agent skills | `llama-index`, `deepeval`, `ragas`, `langchain-openai`, `opentelemetry-api`, `opentelemetry-sdk` |\n| External tools | USEARCH and VSEARCH |\n\n## πŸ”§ Troubleshooting\n\n**PowerShell blocking the launcher?** Run it with an explicit bypass:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\Start_X-Amplicon_WebUI.ps1\n```\n\n**Default port already in use?** Pick a different one with `-Port`:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\Start_X-Amplicon_WebUI.ps1 -Port 8770\n```\n\n**Dependency check failing after install (and you have internet access)?** Open PowerShell in the installation directory and run the repair command:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\Start_X-Amplicon_WebUI.ps1 -RepairDeps\n```\n\n## πŸ“„ License\n\nSee [LICENSE](LICENSE).\n"}