gfalook

A Rust tool for visualizing variation graphs from GFA files.

This is a reimplementation of odgi viz that works directly with GFA files, avoiding the need to convert to ODGI format first.

Citation

Based on the viz command from ODGI:

Guarracino A, Heumos S, Naber F, Panber P, Kelleher J, Garrison E. ODGI: understanding pangenome graphs. Bioinformatics. 2022;38(13):3319-3326. https://doi.org/10.1093/bioinformatics/btac308

Features

• Direct GFA file input (no conversion required)
• PNG and SVG output formats
• Memory-efficient processing
• SHA256-based path coloring (matching odgi)
• Binned mode visualization with multiple coloring modes
• Path clustering by similarity with dendrogram visualization
• Path annotations with legend (e.g., population labels)
• Edge visualization
• X-axis coordinate display

Installation

cargo build --release

Usage

gfalook -i input.gfa -o output.png [OPTIONS]

Examples

All examples use the chr6.C4.gfa test graph.

Basic visualization

gfalook -i graph.gfa -o basic.png -x 1000 -y 500

Depth coloring (-m)

Color by coverage depth using Spectral palette:

gfalook -i graph.gfa -o depth.png -x 1000 -y 500 -m

Depth coloring with RdBu palette (-m -B)

gfalook -i graph.gfa -o depth_rdbu.png -x 1000 -y 500 -m -B RdBu:11

Strand coloring (-S)

Show forward (blue) and reverse (red) strand orientation:

gfalook -i graph.gfa -o strand.png -x 1000 -y 500 -S

Position-based darkness gradient (-d -l)

Color darkness varies by position within each path:

gfalook -i graph.gfa -o darkness.png -x 1000 -y 500 -d -l

White-to-black gradient (-d -u)

gfalook -i graph.gfa -o white_black.png -x 1000 -y 500 -d -u

Link path pieces (-L)

Draw connector lines between discontinuous path segments:

gfalook -i graph.gfa -o links.png -x 1000 -y 500 -L 0.3

Compressed mode (-O)

Single row showing mean coverage across all paths:

gfalook -i graph.gfa -o compressed.png -x 1000 -y 100 -O

Path clustering (-k)

Automatically cluster and reorder paths by similarity. Colored bars on the left indicate cluster membership. Combined with -m for better visibility:

gfalook -i graph.gfa -o clustered.png -x 1000 -y 500 -k -m

Show only cluster representatives (medoids) with -K. Each path label shows the cluster size:

gfalook -i graph.gfa -o clustered_representatives.png -x 1000 -y 500 -k -K -m

Dendrogram visualization (-k -D -m)

Show hierarchical clustering tree alongside paths with depth coloring:

gfalook -i graph.gfa -o dendrogram.png -x 1000 -y 500 -k -D -m

Dendrogram with X-axis (-k -D -m --x-axis)

Combine dendrogram, depth coloring, and absolute X-axis coordinates:

gfalook -i graph.gfa -o dendrogram_xaxis.png -x 1000 -y 500 \
    -k -D -m --x-axis "chm13#chr6:31825251-31908851" --x-axis-absolute

UPGMA hierarchical clustering (--use-upgma)

Use pure UPGMA hierarchical clustering instead of DBSCAN. This creates clusters by cutting the tree at a height threshold:

gfalook -i graph.gfa -o upgma.png -x 1000 -y 500 -k --use-upgma -D -m

Control cluster granularity with --upgma-threshold (0.0-1.0, lower = more clusters):

gfalook -i graph.gfa -o upgma_fine.png -x 1000 -y 500 -k --use-upgma --upgma-threshold 0.3 -D -m

X-axis with pangenomic coordinates (--x-axis pangenomic)

Display coordinates based on node order in the graph:

gfalook -i graph.gfa -o xaxis_pangenomic.png -x 1000 -y 500 --x-axis pangenomic --x-ticks 5

X-axis with path reference (--x-axis <path>)

Display coordinates based on a reference path (e.g., chm13):

gfalook -i graph.gfa -o xaxis_chm13.png -x 1000 -y 500 \
    --x-axis "chm13#chr6:31825251-31908851" --x-ticks 5

X-axis with absolute coordinates (--x-axis-absolute)

Show absolute chromosome coordinates instead of relative positions:

gfalook -i graph.gfa -o xaxis_chm13_abs.png -x 1000 -y 500 \
    --x-axis "chm13#chr6:31825251-31908851" --x-ticks 5 --x-axis-absolute

Path annotations (-E)

Label paths by category (e.g., population, sample type) using an annotation file. The annotation file is a CSV or TSV with two columns: prefix and annotation. Each prefix is matched against path names (longest match wins), and categories are displayed as a centered legend at the top with colored indicators next to each path.

gfalook -i graph.gfa -o annotation.png -x 1000 -y 500 \
    -E test/hprc_year1_samples.csv

Example annotation file (test/hprc_year1_samples.csv) - includes all 234 HPRC Year 1 samples with their population codes:

prefix,annotation
HG00438,CHS
HG00621,CHS
HG01891,ACB
...
CHM13,REF
GRCh38,REF
HG002,NA
HG005,NA

Annotations with clustering (-E -k -D -m --x-axis)

Combine path annotations with clustering, dendrogram, depth coloring, and x-axis coordinates:

gfalook -i graph.gfa -o annotation_clustered.png -x 1000 -y 500 \
    -E test/hprc_year1_samples.csv -k -D -m \
    --x-axis "chm13#chr6:31825251-31908851" --x-axis-absolute

This example shows all visualization features combined: legend at top, dendrogram on left, cluster bar, annotation bar (with a gap between them), path names, depth coloring, and x-axis with absolute coordinates at the bottom.

License

MIT License - see LICENSE for details.

Related Projects

• odgi - Optimized Dynamic Genome/Graph Implementation
• vg - Variation graph toolkit