Package 'panpathAudit'

Audit sequence preservation in GFA traversals

Description

Audits FASTA sequences against named GFA paths and walks without claiming to validate graph topology.

---

Audit FASTA sequences against GFA traversals

Description

Compares source sequences with named GFA P paths and coordinate-aware W walks. Graph topology is not validated.

Usage

auditGFA(
  fasta,
  gfa,
  mapping = NULL,
  statistics = c("basic", "comprehensive"),
  threads = 1L,
  memoryMiB = 1024L,
  alignmentMaxCells = 10000000
)

Arguments

fasta	Character vector of FASTA paths.
gfa	One GFA path.
mapping	Optional data frame with one row per FASTA. See Details.
statistics	Either "basic" or "comprehensive".
threads	Positive worker count.
memoryMiB	Positive tracked-memory limit in MiB.
alignmentMaxCells	Positive comprehensive-alignment limit.

Details

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.

Mapping modes are exact, pansn, and prefix. PanSN rows require sample and numeric haplotype; prefix rows require prefix.

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.

Value

A PanPathAuditResult.

Examples

fasta <- system.file("extdata", "example.fa", package = "panpathAudit")
gfa <- system.file("extdata", "example.gfa", package = "panpathAudit")
result <- auditGFA(fasta, gfa)
auditOutcomes(result)

---

Audit result class

Description

Stores traversal outcomes, summary counts, optional comprehensive statistics, provenance, and memory telemetry.

Usage

auditOutcomes(x)
auditSummary(x)
auditStatistics(x)
auditProvenance(x)
auditTelemetry(x)

Arguments

x	A PanPathAuditResult.

Value

auditOutcomes() returns a DataFrame. Other accessors return SimpleList objects. as.data.frame() returns the outcomes as a base data frame.

Outcome columns

identifier

Mapped path or walk identifier.

source_index

One-based FASTA index.

status

IDENTICAL, DIVERGENT, MISSING_PATH, or MISSING_SOURCE.

record_type

P 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_kind

BASE, 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_delta

Graph 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_distance

Edit distance when alignment completed.

alignment_status

not_applicable, not_required, complete, limit_exceeded, or memory_limit_exceeded.

Columns that do not apply contain NA.

Accessor structures

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.

Examples

fasta <- system.file("extdata", "example.fa", package = "panpathAudit")
gfa <- system.file("extdata", "example.gfa", package = "panpathAudit")
result <- auditGFA(fasta, gfa)
summary(result)

---