agtools API Reference
UnitigGraph
Represents a unitig-level assembly graph parsed from a GFA file.
| Attributes: |
|
|---|
Methods:
| Name | Description |
|---|---|
from_gfa |
Parse a GFA file into a UnitigGraph object. |
get_segment_sequence |
Retrieve a DNA sequence for a segment. |
get_neighbors |
Get neighboring segments of a given segment. |
get_adjacency_matrix |
Return the adjacency matrix as a matrix or a pandas DataFrame. |
is_connected |
Check if there is a path between two segments in the graph. |
get_connected_components |
Get connected components of the graph. |
calculate_average_node_degree |
Calculate the average node degree of the graph. |
calculate_total_length |
Calculate the total length of all segments in the graph. |
calculate_average_segment_length |
Calculate the average segment length. |
calculate_n50_l50 |
Calculate N50 and L50 for the segments in the graph. |
get_gc_content |
Calculate the GC content of segment sequences. |
Examples:
>>> from agtools.core.unitig_graph import UnitigGraph
>>> ug = UnitigGraph.from_gfa("assembly.gfa")
>>> ug.vcount
42
>>> ug.ecount
80
References
GFA: Graphical Fragment Assembly (GFA) Format Specification https://github.com/GFA-spec/GFA-spec
calculate_average_node_degree()
Calculate the average node degree of the graph.
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> ug.calculate_average_node_degree()
2.576374745417515
calculate_average_segment_length()
Calculate the average segment length.
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> ug.calculate_average_segment_length()
8490.319755600814
calculate_n50_l50()
Calculate N50 and L50 for the segment in the graph.
| Returns: |
|
|---|
Examples:
>>> ug.calculate_n50_l50()
(15000, 12)
calculate_total_length()
Calculate the total length of all segments in the graph.
| Returns: |
|
|---|
Examples:
>>> ug.calculate_total_length()
350000
from_gfa(file_path)
classmethod
Parse a GFA file into a UnitigGraph object.
| Parameters: |
|
|---|
| Returns: |
|
|---|
Examples:
>>> ug = UnitigGraph.from_gfa("assembly.gfa")
>>> ug.vcount
42
>>> ug.ecount
80
get_adjacency_matrix(type='matrix')
Return the adjacency matrix as igraph or pandas DataFrame.
| Parameters: |
|
|---|
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> matrix = ug.get_adjacency_matrix()
>>> isinstance(matrix, list)
True
>>> df = ug.get_adjacency_matrix(type="pandas")
>>> df.head()
unitig_1 unitig_2 unitig_3
unitig_1 0 1 0
unitig_2 1 0 1
unitig_3 0 1 0
get_connected_components()
Get connected components of the graph.
| Returns: |
|
|---|
Examples:
>>> components = ug.get_connected_components()
>>> len(components)
3
>>> [len(c) for c in components]
[10, 8, 5]
>>> components[0]
[0, 1, 2, 3, ...]
get_gc_content()
Calculate the GC content of segment sequences.
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> round(ug.get_gc_content(), 2)
0.42
get_neighbors(seg_name)
Get neighboring segments of a given segment.
| Parameters: |
|
|---|
| Returns: |
|
|---|
Examples:
>>> ug.get_neighbors("unitig_1")
['unitig_2', 'unitig_3']
get_path(path_name)
Retrieve the segment string and overlaps string of a path.
This method retrieves the segment string and overlaps string of a path from the original GFA file using byte offsets.
| Parameters: |
|
|---|
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> ug.get_path("path_1")
('unitig_1+,unitig_2+,unitig_3+', '*')
get_segment_sequence(seg_name)
Retrieve a DNA sequence for a segment.
This method retrieves the sequence of a segment from the original GFA file using byte offsets, without loading all sequences into memory at once.
| Parameters: |
|
|---|
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> ug.get_segment_sequence("unitig_1")[:10]
'ATGCGTACGG'
is_connected(from_seg, to_seg)
Check if there is a path between two segments in the graph.
This method determines whether a path exists between the segment
specified by from_seg and the segment specified by to_seg
using the underlying graph's shortest path search.
| Parameters: |
|
|---|
| Returns: |
|
|---|
Examples:
>>> ug.is_connected("unitig_1", "unitig_2")
True
ContigGraph
Represents a contig-level assembly graph derived from a GFA file.
| Attributes: |
|
|---|
Methods:
| Name | Description |
|---|---|
get_contig_sequence |
Retrieve a DNA sequence for a contig. |
get_neighbors |
Get neighboring contigs of a given contig. |
get_adjacency_matrix |
Return the adjacency matrix as igraph or pandas DataFrame. |
is_connected |
Check if there is a path between two contigs in the graph. |
get_connected_components |
Get connected components of the graph. |
calculate_average_node_degree |
Calculate the average node degree of the graph. |
calculate_total_length |
Calculate the total length of all contigs in the graph. |
calculate_average_contig_length |
Calculate the average contig length. |
calculate_n50_l50 |
Calculate N50 and L50 for the contigs in the graph. |
get_gc_content |
Calculate the GC content of contig sequences. |
calculate_average_contig_length()
Calculate the average contig length.
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> cg.calculate_average_contig_length()
40000
calculate_average_node_degree()
Calculate the average node degree of the graph.
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> cg.calculate_average_node_degree()
1
calculate_n50_l50()
Calculate N50 and L50 for the contigs in the graph.
| Returns: |
|
|---|
Examples:
>>> cg.calculate_n50_l50()
(15000, 12)
calculate_total_length()
Calculate the total length of all contigs in the graph.
| Returns: |
|
|---|
Examples:
>>> cg.calculate_total_length()
120000
get_adjacency_matrix(type='matrix')
Return the adjacency matrix as igraph or pandas DataFrame.
| Parameters: |
|
|---|
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> matrix = cg.get_adjacency_matrix()
>>> isinstance(matrix, list)
True
>>> df = cg.get_adjacency_matrix(type="pandas")
>>> df.head()
contig_1 contig_2 contig_3
contig_1 0 1 0
contig_2 1 0 1
contig_3 0 1 0
get_connected_components()
Get connected components of the graph.
| Returns: |
|
|---|
Examples:
>>> components = cg.get_connected_components()
>>> len(components)
3
>>> [len(c) for c in components]
[10, 8, 5]
>>> components[0]
[0, 1, 2, 3, ...]
get_contig_sequence(contig_name)
Retrieve a DNA sequence for a contig.
This method retrieves the sequence of a contig from the contigs file using byte offsets, without loading all sequences into memory at once.
| Parameters: |
|
|---|
| Returns: |
|
|---|
Examples:
>>> cg.get_contig_sequence("contig_1")
'TTGATGCGACGTACGG'
get_gc_content()
Calculate the GC content of contig sequences.
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> cg.get_gc_content()
0.42
get_neighbors(contig_name)
Get neighboring contigs of a given contig.
| Parameters: |
|
|---|
| Returns: |
|
|---|
Examples:
>>> cg.get_neighbors("contig_1")
['contig_2', 'contig_3']
is_connected(from_contig, to_contig)
Check if there is a path between two contigs in the graph.
This method determines whether a path exists between the contig
specified by from_contig and the contig specified by to_contig
using the underlying graph's shortest path search.
| Parameters: |
|
|---|
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> cg.is_connected("contig_1", "contig_2")
True
FastaParser
A lightweight FASTA parser with on-demand sequence retrieval.
Sequences are fetched lazily, so the whole FASTA file is never held in memory. Two retrieval strategies are used, picked automatically:
- Indexed (fast path). For plain-text and BGZF-compressed FASTA
files, lookups are served by
rsbio-seq <https://github.com/anuradhawick/rsbio-seq>_ through a samtools-style.faiindex (plus a.gziindex for BGZF). The index is built once on first use and reused on later runs, so repeated analyses over the same assembly skip the indexing pass entirely. Record names, offsets and lengths stay on the Rust side rather than being copied into Python dictionaries. - Scanning (fallback). For ordinary gzip files -- which cannot be
randomly accessed -- and for FASTA files with unrecognised extensions,
a byte-offset table is built by scanning the headers, and sequences
are read by seeking. Recompressing such files with
bgzipinstead ofgzipmoves them onto the fast path.
| Attributes: |
|
|---|
Methods:
| Name | Description |
|---|---|
get_sequence |
Retrieve a DNA sequence by sequence name. |
get_index |
Retrieve the file offset of the DNA sequence by sequence name. |
iter_sequences |
Stream every record in file order. |
iter_lengths |
Stream every record's length without reading sequence data. |
Examples:
>>> from agtools.core.fasta_parser import FastaParser
>>> parser = FastaParser("contigs.fasta")
>>> parser.indexed
True
reader
property
The indexed rsbio-seq reader, opened on first use.
Opening it loads the index on the Rust side, which for a few million
contigs costs a few hundred megabytes. Most of what agtools does
with a contigs file -- building a graph, counting contigs, computing
lengths, N50 or membership -- never needs a single base of sequence,
so the reader is not opened until a sequence is actually requested.
get_index(seq_name)
Retrieve the file offset of the DNA sequence by sequence name.
| Parameters: |
|
|---|
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> parser.get_index("contig_1")
8487228
get_sequence(seq_name)
Retrieve a DNA sequence by sequence name.
| Parameters: |
|
|---|
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> seq = parser.get_sequence("contig_1")
>>> len(seq)
1500
>>> seq[:10]
'TGGCTCTTCA'
has_cheap_lengths()
Whether :meth:iter_lengths avoids reading sequence data.
True when an .fai index is in use and lookup keys are the record
IDs, so lengths can be streamed off the index without ambiguity.
iter_lengths()
Iterate over every record's length, in file order.
On the indexed path lengths come straight from the .fai, so no
sequence data is read at all -- counting the bases in a 1 GB assembly
becomes a scan of a few megabytes of index. On the scanning path this
falls back to reading sequences.
| Yields: |
|
|---|
Examples:
>>> total_bases = sum(length for _, length in parser.iter_lengths())
iter_sequences()
Iterate over every record in the FASTA file in file order.
This is a single sequential pass handled by rsbio-seq, which is faster than looking each record up by name when the whole file is needed, and keeps memory flat regardless of assembly size.
| Yields: |
|
|---|
Examples:
>>> total = sum(len(seq) for _, seq in parser.iter_sequences())
lookup_key(seq_name)
Translate a graph-side name into the name used in the FASTA file.
Only MEGAHIT needs a translation; for every other assembler the two names are the same.
| Parameters: |
|
|---|
| Returns: |
|
|---|
agtools.core.seqops
Lightweight nucleotide sequence operations.
Sequences are handled throughout agtools as plain :class:str objects;
these helpers work directly on them.
ambiguity_fraction(sequence)
Calculate the fraction of a sequence that is ambiguous.
A character counts as ambiguous when it is anything other than A,
C, G or T, which covers N, the other IUPAC codes and gap
characters. Counting is case-insensitive. An empty sequence has a fraction
of 0.0.
| Parameters: |
|
|---|
| Returns: |
|
|---|
Examples:
>>> ambiguity_fraction("ATGC")
0.0
>>> ambiguity_fraction("ATNN")
0.5
canonical(sequence)
Return the canonical orientation of a sequence.
The canonical form is whichever of the sequence and its reverse complement sorts first, giving an orientation-independent key for comparing or deduplicating sequences. The comparison ignores case, so a soft-masked sequence and its unmasked equivalent choose the same orientation, but the returned sequence keeps its original case.
| Parameters: |
|
|---|
| Returns: |
|
|---|
Examples:
>>> canonical("TTTT")
'AAAA'
>>> canonical("AAAA")
'AAAA'
clean(sequence, placeholder='N')
Upper-case a sequence and replace every ambiguous character.
Any character that is not A, C, G or T is replaced by
placeholder. The default masks ambiguity codes and gaps to N, which
preserves the length of the sequence. Passing an empty placeholder deletes
them instead, which shortens the sequence and breaks any coordinates
derived from it, such as a GFA LN:i: tag or a link overlap.
| Parameters: |
|
|---|
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> clean("atgcn-")
'ATGCNN'
>>> clean("atgcn-", placeholder="")
'ATGC'
complement(sequence)
Return the complement of a nucleotide sequence.
| Parameters: |
|
|---|
| Returns: |
|
|---|
Examples:
>>> complement("ATGC")
'TACG'
gc_content(sequence)
Calculate the GC content of a nucleotide sequence.
The denominator is the full length of the sequence, so gap characters and
ambiguity codes such as N count towards the total but not towards the
GC count. An empty sequence has a GC content of 0.0.
| Parameters: |
|
|---|
| Returns: |
|
|---|
Examples:
>>> gc_content("ATGC")
0.5
>>> gc_content("")
0.0
gc_count(sequence)
Count the G and C bases in a nucleotide sequence.
Counting is case-insensitive, so soft-masked sequences are counted the same
as unmasked ones. The IUPAC code S (G or C) is counted as a GC base; all
other ambiguity codes and any unrecognised characters are not counted.
| Parameters: |
|
|---|
| Returns: |
|
|---|
Examples:
>>> gc_count("ATGC")
2
>>> gc_count("atgc")
2
orient(sequence, orientation)
Return a sequence in the given orientation.
A + traversal returns the sequence unchanged and a - traversal
returns its reverse complement. A GFA segment with no stored sequence
carries * in the sequence field; that placeholder, and an empty
string, are returned unchanged in either orientation, since there is
nothing to reverse complement.
| Parameters: |
|
|---|
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> orient("ATGC", "+")
'ATGC'
>>> orient("ATGC", "-")
'GCAT'
reverse_complement(sequence)
Return the reverse complement of a nucleotide sequence.
| Parameters: |
|
|---|
| Returns: |
|
|---|
Examples:
>>> reverse_complement("ATGC")
'GCAT'
wrap(sequence, width=DEFAULT_LINE_WIDTH)
Wrap a sequence into fixed-width lines for FASTA output.
| Parameters: |
|
|---|
| Returns: |
|
|---|
| Raises: |
|
|---|
Examples:
>>> wrap("ATGCATGC", width=4)
'ATGC\nATGC'