No sections match your search.
Aviary Web Interface
A live run monitor and results explorer for Aviary/Snakemake workflows. Powered by Flask and served via a self-contained pixi environment — no manual dependency management required. Monitor jobs in real time, explore bin quality, generate charts, and export data — all from your browser.
01Quick Start
Install the environment (first time only) from the web/ folder:
cd /path/to/aviary/aviary/web
~/.pixi/bin/pixi installOn an HPC — open the SSH tunnel first (in a separate local terminal window, keep it open):
ssh -L 8090:localhost:8090 <username>@<hpc-address>This forwards port 8090 from the HPC to your local machine. The tunnel must be open before you try to reach the server in your browser. Skip this step if running locally. See HPC / SSH Tunnel for full details.
Start the server on the HPC (or locally), pointing it at your output directory:
pixi run -e web server --output-dir /path/to/aviary_outputOpen your browser at http://localhost:8090
Select your output directory using the switcher in the top bar if needed, or pass --output-dir on start.
Server arguments
| Argument | Default | Description |
|---|---|---|
--output-dir / -o | current directory | Root directory to scan. The server traverses any subdirectory depth automatically. |
--port / -p | 8090 | Port to listen on |
--host | 127.0.0.1 | Bind address. Keep as loopback on shared HPCs. |
--reload | off | Auto-restart the server when server.py or templates are saved. Useful when making changes to the interface. |
Tip: The server discovers Aviary output directories by recursively searching for.snakemake/log/folders. This works at any nesting depth — including<commit-hash>/assembler/samplelayouts.
02Pipeline Monitor
The main view groups sample cards by run date (derived from Snakemake log timestamps). Each date group shows an overall progress bar for that batch.
Within each date group, every sample has a card showing an assembler pill per assembler (megahit / metaspades) with a live progress bar:
Expanding an assembler pill reveals every individual job (Snakemake rule) with its status, duration, thread count, memory usage, and a link to its log file.
The sidebar overview shows sample count, running, completed, and failed counts scoped to the most recent run only — so historical runs don't inflate the numbers.
Dismissing Failed Runs
When a run fails, a red banner appears on the sample card listing the failed rule(s). If you have already acknowledged the failure and don't want to see the indicator, click Dismiss on the banner. This hides the banner and turns the assembler pill dot grey.
The dismissal is saved in localStorage and is tied to the specific log file — if the sample is re-run and fails again, the red indicator reappears automatically.
Log Viewer
Click any job row to open its log in the right panel.
Error, Failed, Exception, Traceback, or CalledProcessError are highlighted in red. The log auto-scrolls to the first error. If no errors are found it scrolls to the bottom.Auto-Refresh & Countdown
The page refreshes every 60 seconds. A live countdown (in Xs) appears next to the pulse dot in the sidebar footer so you always know when the next update is due.
You can also trigger a manual refresh using the refresh button in the topbar at any time.
Output Directory Switcher
The directory switcher in the top bar lets you hot-swap between multiple Aviary project roots without restarting the server.
Type an absolute path and press Go, or select from the recently-used roots list.
The last 5 roots are persisted via localStorage across browser sessions.
Note: Switching the root updates all data — the job tree, summary, graphs, and export preview all reload using the new path.
03Bin Quality Report
Toggle from Pipeline Monitor to Bin Quality Report using the tab buttons in the top bar to view final results once runs are complete. Grouped by run date, newest first.
Quality tiers
| Tier | Completeness | Contamination |
|---|---|---|
| HQ | ≥ 90% | ≤ 5% |
| MQ | ≥ 50% | ≤ 10% |
| LQ | Everything else | — |
The bin table is sorted HQ → MQ → LQ, then by completeness descending within each tier, so your best bins always appear first.
Columns
| Column | Description |
|---|---|
| Bin | Bin identifier |
| Completeness | CheckM2 completeness estimate (%) |
| Contamination | CheckM2 contamination estimate (%) |
| Strain heterogeneity | CheckM2 strain heterogeneity estimate (%) |
| Genome size | Total assembly length (bp) |
| N50 | Contig N50 (bp) |
| GC content | GC fraction (%) |
| Taxonomy | GTDB-tk classification string (d__Bacteria;p__…) |
Assembly stats
Total assembly length, N50, contig count, and GC content per sample/assembler combination.
04Results Visualisation /graph
A dedicated page for generating publication-quality charts from your results. All six chart types are rendered as inline SVG — no charting libraries required. Select samples on the left, configure the chart above, and the visualisation updates instantly.
| Chart type | What it shows |
|---|---|
| Bar | HQ/MQ/LQ counts, total MAGs, N50, or assembly size per sample. Toggle grouped or stacked mode. |
| Scatter | Any two numeric bin fields plotted against each other. Colour by quality tier, assembler, sample, or domain. Optional bubble-size encoding by a third metric. |
| Histogram | Distribution of any bin quality field (completeness, contamination, N50, …) with adjustable bin count. Threshold lines mark HQ/MQ tiers for completeness and contamination. |
| Phylum stacked bar | GTDB taxonomy breakdown at domain, phylum, or class level. Top-N taxa shown, remainder grouped as "Other". |
| Heatmap | Sample × assembler grid coloured by HQ MAG count, mean completeness, or total wall time. Colour gradient from dark to teal. |
| Donut | Proportional breakdown by quality tier, taxonomic domain, or assembler. Centre hole shows total count. |
Customise Panel
The Customise section (below the chart config) adjusts the appearance of the current chart without regenerating it:
Downloading charts
Use the SVG button to download a vector file suitable for editing in Inkscape / Illustrator, or PNG for a 2× scale raster image ready to embed in documents or presentations.
05Tree View /view
An interactive taxonomy tree built from GTDB-Tk classifications across all bins. The tree is constructed client-side from the taxonomy strings in your bin results — no pre-computed tree file required. Three layout modes are available depending on what you want to explore.
| Layout | Description |
|---|---|
| Sunburst | Default view. Concentric ring chart showing taxonomy from domain outward. Click any segment to zoom into that clade — click the centre circle to go back. Scroll or use the Zoom In / Zoom Out buttons to scale. Best for getting a quick overview of community composition. |
| Radial (Circular) | Classic circular cladogram with phylum-level colour bands. Click nodes to expand or collapse. Best for exploring tree structure at a glance. |
| Horizontal Cladogram | Left-to-right dendrogram. Better for reading full taxonomy labels on deep or species-level trees. |
Controls
Interaction
- Sunburst — click a segment to zoom into that clade. Click the teal centre circle to go back to the full view.
- Radial / Horizontal — click any node to expand or collapse that branch individually.
- Zoom In / Zoom Out buttons in the topbar scale the view in all layouts. Mouse scroll also works.
- Reset View returns to the default zoom and position.
- Expand All / Collapse buttons reset the entire tree structure (radial and horizontal only).
- Drag to pan freely in all layouts.
- Hover any node for a tooltip showing rank, MAG count, and HQ/MQ/LQ breakdown.
Export the current view as SVG or PNG using the Download button in the topbar.
06Contig Assembly Graph /assembly
A per-sample viewer for the GFA-format assembly graphs produced by megahit and metaSPAdes. Browse the graph structure for each sample and assembler combination directly in the browser.
Tip: Assembly graphs are available once theassemble_short_readsstep completes. The graph file is located atdata/short_read_assembly/assembly_graph_with_scaffolds.gfawithin each sample's output directory.
07Export Results /export
A two-panel page for downloading your bin results as a filtered, customised table.
Toggle between CSV and TSV output using the format switch in the config panel, then click Download in the top bar to export the full filtered table.
08HPC / SSH Access
Two terminal windows are required — both opened locally (not already inside an HPC session).
Window 1 — SSH tunnel (keep this open)
ssh -L 8090:localhost:8090 <username>@<hpc-address>This forwards port 8090 on your local machine to port 8090 on the HPC. Keep this window open for the entire session — closing it drops the tunnel and the browser will lose connection.
Window 2 — start the server on the HPC
ssh <username>@<hpc-address>
cd /path/to/aviary/aviary/web
pixi run -e web server --output-dir /path/to/aviary_outputThen open in your browser
http://localhost:809009API Reference
All endpoints accept an optional ?root=<path> query parameter to override the default output directory set at server start.
| Endpoint | Key params | Returns |
|---|---|---|
GET /api/structure |
?root= |
Sample/assembler job tree grouped by run date; root field with resolved path |
GET /api/status |
?output_dir= |
Detailed status for a single output directory |
GET /api/summary |
?root= |
Bins and assembly stats for all runs |
GET /api/logs |
?output_dir= |
List of available Snakemake log files for a directory |
GET /api/job_log |
?log_path=, ?output_dir= |
Log file content + available_attempts array of sibling attempt log paths |
GET /api/benchmark |
?benchmark_path=, ?output_dir= |
Benchmark timing data (wall time, CPU, memory) for a job |
GET /api/output_dirs |
?root= |
All discovered output directories under the root |
GET /api/gfa_stats |
?output_dir= |
Parsed GFA assembly graph statistics for a single output directory. Results are cached by file mtime. |
GET /api/gfa_available |
?root= |
Map of all discovered output directories to a boolean indicating whether assembly/assembly_graph.gfa exists |
GET /api/taxonomy_tree |
?root= |
Taxonomy breakdown tree — prefers SingleM condensed profile data when available, falls back to GTDB-Tk classification strings |
GET /api/singlem_status |
?root= |
Count of output directories that have a SingleM condensed profile (total and done keys) |
GET /api/phylo_newick |
?output_dir=, ?root= |
GTDB-Tk Newick tree with MAG annotations for the tree view (output_dir or auto-detected from root) |
No auth: The server is intended for local or SSH-tunnelled use only. It has no authentication. Do not expose it publicly.