Skip to main content

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}