Assembly Graph File Formats

Assembly graphs describe the structure of DNA assemblies using nodes (segments or contigs) and edges (connections or overlaps). Several file formats are used to represent these graphs, each with its own syntax and conventions.

This page summarises the four most common formats supported by agtools.

GFA

Extension: .gfa

Versions supported: GFA1 (commonly used in assembly)

GFA (Graphical Fragment Assembly) is a standard format for describing genome assemblies as graphs, where:

  • Headers (start with the tag H) denote metadata.
  • Segments (start with the tag S) are nodes (contigs or unitigs).
  • Links (start with the tag L) define edges between segments.
  • Paths (start with the tag P) optionally define traversal orders.

agtools also supports the tags J, C, and W. Please refer to the GFA specification for further details.

Example

S   unitig1 ATGCGTACGGGGTAAGTGAGCCTG
S   unitig2 CGGTACCTTAAAGTCTGG
L   unitig1 +   unitig2 -   10M
P   contig1 unitig1+,unitig2-   10M

References: GFA Format

FASTG

Extension: .fastg

FASTG represents possible assembly paths using a FASTA-like structure that encodes graph topology.

Each node (NODE_X) in the graph (contig or unitig) contains:

  • A path label (e.g. :neighbor1,neighbor2...) describing outgoing edges.
  • A sequence entry representing the nucleotide sequence.

This is followed by a reverse-complement entry (NODE_X'). See the example below.

Example

>NODE_1:NODE_2';
ATGCGTACGTTAG
>NODE_1';
CTAACGTACGCAT
>NODE_2:NODE_1',NODE_3';
CGGTAACCTGACC
>NODE_2';
GGTCAGGTTACCG
>NODE_3:NODE_2';
TTGACCGGATCGA
>NODE_3';
TCGATCCGGTCAA

References: FASTG Format

Note: The FASTG format described in the official FASTG specification differs substantially from the FASTG files produced by MEGAHIT and early versions of SPAdes (prior to version 3.10.0).

ASQG

Extension: .asqg

The ASQG format represents assembly graphs using overlapping contigs.

  • Header records (start with the tag HT) denote metadata.
  • Vertex records (start with the tag VT) denote the sequences.
  • Edge description records (start with the tag ED) denote pairs of overlapping sequences.

Example

HT  VN:i:1  ER:f:0  OL:i:45 IN:Z:reads.fa   CN:i:1  TE:i:0
VT  read1   GATCGATCTAGCTAGCTAGCTAGCTAGTTAGATGCATGCATGCTAGCTGG
VT  read2   CGATCTAGCTAGCTAGCTAGCTAGTTAGATGCATGCATGCTAGCTGGATA
VT  read3   ATCTAGCTAGCTAGCTAGCTAGTTAGATGCATGCATGCTAGCTGGATATT
ED  read2 read1 0 46 50 3 49 50 0 0
ED  read3 read2 0 47 50 2 49 50 0 0

References: ASQG Format

DOT

Extension: .dot (GraphViz) or .gv (ABySS)

DOT files describe general graphs and can be used to render visual diagrams of assembly graphs.

Example

graph {
  0 [
    id=0
    name=1
  ];
  1 [
    id=1
    name=2
  ];
  2 [
    id=2
    name=3
  ];
  3 [
    id=3
    name=4
  ];
  4 [
    id=4
    name=5
  ];

  1 -- 0;
  2 -- 1;
  3 -- 1;
  4 -- 2;
  4 -- 3;
}

To view it using GraphViz:

dot -Tpng graph.dot -o graph.png

References: GraphViz DOT Format

The same example graph can be represented in ABySS DOT format, where:

  • l denotes sequence length
  • d denotes overlap length

Example

digraph g {
"1+" [l=8]
"1-" [l=8]
"2+" [l=8]
"2-" [l=8]
"3+" [l=8]
"3-" [l=8]
"4+" [l=8]
"4-" [l=8]
"5+" [l=8]
"5-" [l=8]
"1+" -> "2+" [d=-7]
"2-" -> "1-" [d=-7]
"2+" -> "3+" [d=-7]
"3-" -> "2-" [d=-7]
"2+" -> "4+" [d=-7]
"4-" -> "2-" [d=-7]
"3+" -> "5+" [d=-7]
"5-" -> "3-" [d=-7]
"4+" -> "5+" [d=-7]
"5-" -> "4-" [d=-7]
}

References: ABySS DOT Format


Comparison of Assembly Graph File Formats

Feature GFA FASTG ASQG DOT (GraphViz / ABySS)
Primary use General-purpose assembly graph representation Compact representation of assembly paths Read overlap graphs Visualisation and graph layout
Typical extension .gfa .fastg .asqg .dot, .gv
Graph type Directed graph Directed graph Directed graph Directed or undirected
Nodes represent Segments / unitigs Contigs or unitigs Reads or contigs Generic graph nodes
Edges represent Overlaps / links Traversable paths Sequence overlaps Graph connections
Stores sequences ✅ Yes ✅ Yes ✅ Yes ❌ No
Stores overlaps ✅ Yes ✅ Implicitly ✅ Yes Optional
Supports paths ✅ Yes (P records) ✅ Yes (via node labels) ❌ No ❌ No
Orientation-aware ✅ Yes ✅ Yes ✅ Yes Optional
Standardised ✅ Yes (GFA1) ⚠️ Semi-standard ❌ Tool-specific ✅ GraphViz
Used by assemblers SPAdes, Flye, hifiasm MEGAHIT SGA ABySS
Supported by agtools ✅ Full support ✅ Supported ✅ Supported ✅ Supported
Best for General graph analysis Path-centric graphs Overlap-based assemblies Visualisation
Visualisation support Via Bandage Via Bandage Limited Native (GraphViz)

Summary

Format When to Use
GFA Best all-purpose format for assembly graphs; recommended default
FASTG Useful when working with assembler-generated paths
ASQG Suitable for overlap-based assemblies
DOT Best for visualisation and debugging

Compressed input files

Every file agtools reads can be supplied either as plain text or gzip-compressed. Compression is detected from the file contents, so the .gz suffix is conventional rather than required:

agtools gfa2fasta -g assembly_graph.gfa.gz -o segments.fasta
agtools stats -g assembly_graph.gfa.gz

This applies to GFA, FASTG, ASQG, contig FASTA files, and the assembler path/info files (contigs.paths, assembly_info.txt). Output files are always written uncompressed.

A note on gzip versus BGZF

FASTA files are read through rsbio-seq, which serves sequence lookups from a samtools-style .fai index. Index files are created automatically beside the FASTA file the first time it is read, and reused afterwards.

Random access needs a block-compressed file, so the index can only be used for plain-text FASTA and for BGZF-compressed FASTA (what bgzip produces). An ordinary gzip file is a single compressed stream: reaching a record means decompressing everything before it, so no index can help. Such files still work, but agtools falls back to scanning them and logs a warning.

The difference is large and grows with file size. On a 22 MB contigs file (96,751 contigs), 100 random sequence lookups took 0.03 s from a plain or BGZF file and 4.5 s from an ordinary gzip file. If your contigs are gzipped, recompressing once is worth it:

gunzip -c contigs.fasta.gz | bgzip > contigs.fasta.gz.tmp
mv contigs.fasta.gz.tmp contigs.fasta.gz

BGZF files are valid gzip files, so other tools read them unchanged.

What the index buys you

The .fai records every contig's name, length and offset, so agtools answers a good deal without touching sequence data at all. Counting contigs, listing names, testing membership, and computing total length, average length and N50/L50 are all served from the index. Only operations that genuinely need bases -- get_contig_sequence, get_gc_content, gfa2fasta -- read the FASTA file, and the indexed reader is not even opened until one of them is called.

On a 788 MB SPAdes assembly (1.74 million contigs) this makes calculate_total_length and calculate_n50_l50 run in about a second rather than reading 788 MB of sequence.