pangraphx_core/lib.rs
1//! Core library for `PanGraphX`.
2//!
3//! `pangraphx-core` provides a unified API for parsing, converting, and manipulating
4//! pangenome graph formats.
5//!
6//! # What this crate provides
7//!
8//! - A common graph DTO: [`CoreGraphDTO`]
9//! - A mutable graph type with lookup/manipulation helpers: [`CoreGraph`]
10//! - Format dispatch through [`GraphFormat`]
11//! - Parser/serializer traits: [`traits::GraphParser`] and [`traits::GraphSerializer`]
12//! - de Bruijn graph utilities: [`DeBruijn`] and related types
13//!
14//! # Supported formats
15//!
16//! See [`GraphFormat`] for currently supported formats and extension mapping.
17//!
18//! # Quick start
19//!
20//! Parse a graph and serialize it to another format:
21//!
22//! ```no_run
23//! use std::fs::File;
24//! use pangraphx_core::GraphFormat;
25//!
26//! fn main() -> Result<(), Box<dyn std::error::Error>> {
27//! let mut input = File::open("graph.gfa")?;
28//! let parser = GraphFormat::GFA.get_parser();
29//! let graph = parser.parse(&mut input)?;
30//!
31//! let serializer = GraphFormat::GBZ.get_serializer();
32//! let mut output = File::create("graph.gbz")?;
33//! serializer.serialize(&graph, &mut output)?;
34//! Ok(())
35//! }
36//! ```
37//!
38//! Build a de Bruijn graph from a parsed directed graph:
39//!
40//! ```no_run
41//! use std::fs::File;
42//! use pangraphx_core::{CoreGraphDTO, DeBruijn, GraphFormat};
43//!
44//! fn main() -> Result<(), Box<dyn std::error::Error>> {
45//! let mut input = File::open("graph.vg")?;
46//! let parser = GraphFormat::VG.get_parser();
47//! let graph: CoreGraphDTO = parser.parse(&mut input)?;
48//!
49//! let dbg = DeBruijn::from_directed_graph(graph, 31)?;
50//! // One node per k-mer, or `dbg.into_compacted_dto()?` for unitigs.
51//! let _as_core = CoreGraphDTO::try_from(dbg)?;
52//! Ok(())
53//! }
54//! ```
55//!
56//! # Errors
57//!
58//! Library APIs typically return [`PanResult<T>`](PanResult), an alias around
59//! [`PanGraphXError`]
60
61pub mod core;
62pub mod de_bruijn_conversion;
63pub mod error;
64pub mod formats;
65pub mod proto_gen;
66pub mod traits;
67
68/// Common graph primitive types used throughout the crate.
69pub use core::core_types::{
70 Edge, Node, NodeId, NodeName, Orientation, Path, PathName, Sequence, Step,
71};
72/// Graph statistics summary types produced by [`CoreGraph::compute_stats`].
73pub use core::stats::{DegreeStats, GraphStats, LenStats, PathStats};
74/// Internal graph model with efficient lookup and manipulation utilities.
75pub use core::{graph::CoreGraph, graph_dto::CoreGraphDTO};
76/// de Bruijn graph data structures and helpers.
77pub use de_bruijn_conversion::{colored_dbg::ColoredDBG, de_bruijn_graph::DeBruijn, k_mers::Kmer};
78/// Standard result type for public APIs in this crate.
79pub use error::PanResult;
80use std::fmt::Display;
81
82use crate::error::PanGraphXError;
83use crate::formats::{FastgCodec, GBZCodec, GFACodec, ODGICodec, VGCodec};
84use crate::traits::{GraphParser, GraphSerializer};
85use std::io::{Read, Seek};
86
87/// Supported graph formats
88#[derive(Debug, Clone, Copy, PartialEq, Eq)]
89pub enum GraphFormat {
90 /// GBZ compressed graph format.
91 GBZ,
92 /// Graphical Fragment Assembly format.
93 GFA,
94 /// Variation Graph format.
95 VG,
96 /// FASTG graph format.
97 FASTG,
98 /// ODGI binary graph format.
99 ODGI,
100}
101
102impl Display for GraphFormat {
103 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
104 match self {
105 Self::GBZ => write!(f, "GBZ"),
106 Self::GFA => write!(f, "GFA"),
107 Self::VG => write!(f, "VG"),
108 Self::FASTG => write!(f, "FASTG"),
109 Self::ODGI => write!(f, "ODGI"),
110 }
111 }
112}
113
114impl GraphFormat {
115 /// Returns an iterator over all supported formats.
116 pub fn iter() -> impl Iterator<Item = Self> {
117 [Self::GFA, Self::GBZ, Self::VG, Self::FASTG, Self::ODGI].into_iter()
118 }
119
120 /// Returns the conventional filename extension for this format.
121 #[must_use]
122 pub const fn get_extension(&self) -> &str {
123 match self {
124 Self::GBZ => "gbz",
125 Self::GFA => "gfa",
126 Self::VG => "vg",
127 Self::FASTG => "fastg",
128 Self::ODGI => "og",
129 }
130 }
131
132 /// Resolves a format from a filename extension.
133 ///
134 /// Matching is case-insensitive.
135 ///
136 /// # Errors
137 /// Returns an error if the extension does not correspond to a supported format.
138 pub fn from_extension(extension: &str) -> PanResult<Self> {
139 match extension.to_lowercase().as_str() {
140 "gfa" => Ok(Self::GFA),
141 "vg" => Ok(Self::VG),
142 "gbz" => Ok(Self::GBZ),
143 "fastg" => Ok(Self::FASTG),
144 "og" => Ok(Self::ODGI),
145 _ => Err(PanGraphXError::UnsupportedFormat),
146 }
147 }
148
149 /// Returns a parser implementation for the selected format.
150 #[must_use]
151 pub fn get_parser<R: Read + Seek>(&self) -> Box<dyn GraphParser<R>> {
152 match self {
153 Self::GFA => Box::new(GFACodec),
154 Self::VG => Box::new(VGCodec),
155 Self::GBZ => Box::new(GBZCodec),
156 Self::FASTG => Box::new(FastgCodec),
157 Self::ODGI => Box::new(ODGICodec),
158 }
159 }
160
161 /// Returns a serializer implementation for the selected format.
162 #[must_use]
163 pub fn get_serializer(&self) -> Box<dyn GraphSerializer> {
164 match self {
165 Self::GFA => Box::new(GFACodec),
166 Self::VG => Box::new(VGCodec),
167 Self::GBZ => Box::new(GBZCodec),
168 Self::FASTG => Box::new(FastgCodec),
169 Self::ODGI => Box::new(ODGICodec),
170 }
171 }
172
173 #[must_use]
174 pub const fn get_description(&self) -> &str {
175 match self {
176 Self::GFA => {
177 "Graphical Fragment Assembly (v1.0/v1.1): An interoperable, text-based standard for representing pangenome nodes, edges, and paths."
178 }
179 Self::VG => {
180 "VG Protobuf: A serialized binary format used by the vg toolkit; supports rich metadata but can be storage-intensive."
181 }
182 Self::GBZ => "GBZ: A highly compressed format for large pangenomes.",
183 Self::FASTG => {
184 "FASTG: A text-based format designed to capture assembly ambiguities; largely superseded by GFA in modern workflows."
185 }
186 Self::ODGI => {
187 "ODGI: A dynamic, memory-efficient binary format optimized for large-scale pangenome analysis and graph manipulation."
188 }
189 }
190 }
191}