| Title: | Audit Sequence Preservation in GFA Traversals |
|---|---|
| Description: | Audits source FASTA sequences against named paths and coordinate-aware walks in GFA files. It reports exact recovery, divergence coordinates, digests, and optional base-level statistics. Graph topology is not validated. |
| Authors: | Anestis Gkanogiannis [aut, cre] (ORCID: <https://orcid.org/0000-0002-6441-0688>), Jack O'Connor [cph] (Author of the bundled BLAKE3 C implementation in src/vendor/blake3 (CC0 license)), Samuel Neves [cph] (Author of the bundled BLAKE3 C implementation in src/vendor/blake3 (CC0 license)), Alain Mosnier [cph] (Author of the bundled SHA-256 implementation in src/vendor/sha256 (0BSD license)) |
| Maintainer: | Anestis Gkanogiannis <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.99.3 |
| Built: | 2026-11-18 21:27:47 UTC |
| Source: | https://github.com/bioc/panpathAudit |
Audits FASTA sequences against named GFA paths and walks without claiming to validate graph topology.
For each traversal, panpathAudit reports whether the sequence spelled by
a GFA P path or coordinate-aware W walk is identical to its
source FASTA record. Every traversal gets SHA-256 and BLAKE3 digests of the
source and graph sequences, and divergent traversals also get the coordinates
of the first difference. Optionally, the package also computes base-level
comparison statistics. Links, overlaps beyond blunt joins, and connectivity are not
checked.
The main entry point is auditGFA(), which takes one or more FASTA
files (plain or gzip-compressed), one GFA file, and an optional mapping
between FASTA files and path or walk names. It returns a
PanPathAuditResult object, whose contents are read with
these accessors:
auditOutcomes(): one row per traversal, as a
DataFrame.
auditSummary(): counts and percentages per outcome
status.
auditStatistics(): base-level statistics when
statistics = "comprehensive".
auditProvenance(): inputs, settings, and versions used.
auditTelemetry(): memory limit, peak tracked memory,
and thread count.
The native engine is a C++ port of the Rust command-line tool
panpath-audit (https://github.com/gkanogiannis/panpath-audit). See
system.file("PROVENANCE.md", package = "panpathAudit") for the port,
bundled third-party code, and example data.
The vignette gives a worked introduction:
vignette("panpathAudit", package = "panpathAudit").
Anestis Gkanogiannis [email protected]
Maintainer: Anestis Gkanogiannis [email protected]
Gkanogiannis, A. (2026). Panpath-Audit: Sequence-Level Verification of Embedded Pangenome Paths Against Source Assemblies. Preprints. doi:10.20944/preprints202608.1872.v1
auditGFA to run an audit;
PanPathAuditResult for the result class and its
accessors.
Package website and issue tracker: https://github.com/gkanogiannis/panpathAudit
fasta <- system.file("extdata", "example.fa", package = "panpathAudit") gfa <- system.file("extdata", "example.gfa", package = "panpathAudit") result <- auditGFA(fasta, gfa) result summary(result)fasta <- system.file("extdata", "example.fa", package = "panpathAudit") gfa <- system.file("extdata", "example.gfa", package = "panpathAudit") result <- auditGFA(fasta, gfa) result summary(result)
Compares source sequences with named GFA P paths and coordinate-aware
W walks. Graph topology is not validated.
auditGFA( fasta, gfa, mapping = NULL, statistics = c("basic", "comprehensive"), threads = 1L, memoryMiB = 1024L, alignmentMaxCells = 10000000 )auditGFA( fasta, gfa, mapping = NULL, statistics = c("basic", "comprehensive"), threads = 1L, memoryMiB = 1024L, alignmentMaxCells = 10000000 )
fasta |
The source sequences, as one of:
Records are matched to GFA traversals by name, after applying
|
gfa |
|
mapping |
Columns that a row's mode does not use may be omitted or left as |
statistics |
|
threads |
|
memoryMiB |
|
alignmentMaxCells |
|
Gzip input is detected from file content. GFA P records must use blunt
overlaps (* or 0M). W identifiers are formed as
sample#haplotype#sequence; their ranges are zero-based and half-open.
Use mapping when FASTA record names differ from the GFA path or walk
names, for example when walk names follow the PanSN convention
(sample#haplotype#name). See the mapping argument for the
supported modes and columns.
A running audit can be interrupted with Ctrl-C (or Esc in the R GUI). Worker
threads are stopped, and an R interrupt condition is signalled; no
partial result is returned.
Argument, input, and operational failures raise conditions with classes
panpathAudit_argument_error, panpathAudit_input_error, and
panpathAudit_operational_error. Each inherits from
panpathAudit_error and carries a diagnostics DataFrame.
Diagnostic positions are one-based.
fasta <- system.file("extdata", "example.fa", package = "panpathAudit") gfa <- system.file("extdata", "example.gfa", package = "panpathAudit") result <- auditGFA(fasta, gfa) auditOutcomes(result)fasta <- system.file("extdata", "example.fa", package = "panpathAudit") gfa <- system.file("extdata", "example.gfa", package = "panpathAudit") result <- auditGFA(fasta, gfa) auditOutcomes(result)
Stores traversal outcomes, summary counts, optional comprehensive statistics, provenance, and memory telemetry.
auditOutcomes(x) auditSummary(x) auditStatistics(x) auditProvenance(x) auditTelemetry(x)auditOutcomes(x) auditSummary(x) auditStatistics(x) auditProvenance(x) auditTelemetry(x)
x |
A |
auditOutcomes() returns a DataFrame. Other accessors return
SimpleList objects. as.data.frame() returns the outcomes as a
base data frame.
identifierMapped path or walk identifier.
source_indexOne-based FASTA index.
statusIDENTICAL, DIVERGENT,
MISSING_PATH, or MISSING_SOURCE.
record_typeP or W.
source_start_0based, source_end_0based_exclusive
Walk source range.
source_length, graph_length,
addressed_source_bases
Sequence and addressed-range sizes.
divergence_kindBASE, END, or
RANGE_LENGTH.
source_position_1based, graph_position_1based
First divergent base position.
segment, orientation
Segment and traversal strand at the divergence.
traversal_position_1based,
segment_position_1based
Divergence coordinates within the traversal and segment.
range_length, walk_length
Expected and reconstructed sizes for a walk range mismatch.
source_sha256, addressed_source_sha256,
graph_sha256
SHA-256 digests.
source_blake3, addressed_source_blake3,
graph_blake3
BLAKE3 digests.
source_ambiguous_bases, graph_ambiguous_bases,
ambiguous_columns
IUPAC ambiguity counts.
length_deltaGraph length minus addressed source length.
matched, substituted, source_only,
graph_only
Aligned base counts.
not_embedded, missing_path_bases,
missing_source_bases
Unrepresented base counts.
unaligned_divergent_source,
unaligned_divergent_graph
Divergent bases not aligned because of a resource limit.
edit_distanceEdit distance when alignment completed.
alignment_statusnot_applicable, not_required,
complete, limit_exceeded, or
memory_limit_exceeded.
Columns that do not apply contain NA.
auditSummary() contains counts, percentages, and
total. auditStatistics() is empty in basic mode; otherwise it
contains global, by_source, and by_record_type aggregates.
Each aggregate reports sequence and base totals, ambiguity counts, edit and
alignment totals, base-category counts, and status counts.
auditProvenance() records package and reference versions, normalized
input paths, mapping and resource options, compression, GFA version and record
counts, overlap interpretation, and the false topology_validated flag.
auditTelemetry() contains limit_bytes,
peak_tracked_bytes, oversized_contigs, and threads.
fasta <- system.file("extdata", "example.fa", package = "panpathAudit") gfa <- system.file("extdata", "example.gfa", package = "panpathAudit") result <- auditGFA(fasta, gfa) summary(result)fasta <- system.file("extdata", "example.fa", package = "panpathAudit") gfa <- system.file("extdata", "example.gfa", package = "panpathAudit") result <- auditGFA(fasta, gfa) summary(result)