[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"vWYGXp5yUW":3},"# povu · [![Test Status](https://github.com/pangenome/povu/actions/workflows/test.yml/badge.svg?label=tests)](https://github.com/pangenome/povu/actions/workflows/test.yml) [![C++17 Build (CMake, macOS)](https://github.com/pangenome/povu/actions/workflows/macos.yml/badge.svg)](https://github.com/pangenome/povu/actions/workflows/macos.yml) [![C++17 Build (CMake, Ubuntu)](https://github.com/pangenome/povu/actions/workflows/build_cmake.yml/badge.svg)](https://github.com/pangenome/povu/actions/workflows/build_cmake.yml) ![c++17](https://img.shields.io/badge/C++-17-informational.svg?style=flat&logo=c%2B%2B&logoColor=white) [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](https://opensource.org/licenses/MIT)\n\nA toolkit for exploring regions of genomic variation\n\n## Table of Contents\n- [Usage and Examples](#usage-and-examples)\n- [Rust Bindings](#rust-bindings)\n- [Building povu](#building-povu)\n  - [Installing with Guix](#installing-with-guix)\n  - [Building specific target](#building-specific-target)\n  - [Development](#development)\n- [Repository Structure](#repository-structure)\n\n\n## Usage and Examples\n\nFor general help, run:\n\n```bash\n./bin/povu -h\n# or simply\n./bin/povu\n```\n\nThe table below summarizes the subcommands currently available:\n\n| Subcommand | Description                            |\n|------------|--------------------------------------- |\n| gfa2vcf    | Convert GFA to VCF (decompose + call)  |\n| decompose  | Identify regions of variation          |\n| call       | Generate VCF from regions of variation |\n| info       | Print graph information                |\n\nFor detailed documentation on each subcommand, refer to the [docs/](./docs) directory.\n\n### Quick Start: GFA to VCF\n\nThe simplest way to call variants is using `gfa2vcf`:\n\n```bash\n# Convert GFA to VCF using path prefix\n./bin/povu gfa2vcf -i input.gfa -P HG > output.vcf\n\n# Using a reference list file\n./bin/povu gfa2vcf -i input.gfa -r ref_list.txt > output.vcf\n```\n\nThe `gfa2vcf` command internally handles all intermediate steps and outputs a combined VCF to stdout.\n\n### Two-Step Workflow\n\nFor more control, use the separate `decompose` and `call` commands:\n\n```bash\n# Step 1: Identify regions of variation\n./bin/povu decompose -i input.gfa -o regions/\n\n# Step 2a: Generate separate VCF files (one per reference)\n./bin/povu call -i input.gfa -f regions/ -r ref_list.txt -o vcf_output/\n\n# Step 2b: Generate single combined VCF to stdout\n./bin/povu call -i input.gfa -f regions/ -r ref_list.txt --stdout > output.vcf\n```\n\n## Rust Bindings\n\nPovu provides Rust bindings for embedding pangenome variation analysis in Rust applications. The bindings are located in the `povu-rs/` directory and offer both high-level convenience methods and detailed topology access.\n\n### Quick Start (Rust)\n\nAdd to your `Cargo.toml`:\n```toml\n[dependencies]\npovu = { git = \"https://github.com/pangenome/povu\", branch = \"rust\" }\n```\n\n### Example: Build a graph in memory\n\n```rust\nuse povu::{PovuGraph, Orientation};\n\n// Create an empty graph\nlet mut graph = PovuGraph::new(10, 15, 0);\n\n// Add vertices\ngraph.add_vertex(1, \"AAAA\")?;\ngraph.add_vertex(2, \"GGGG\")?;\ngraph.add_vertex(3, \"TTTT\")?;\ngraph.add_vertex(4, \"CCCC\")?;\n\n// Add edges to create a diamond (bubble)\ngraph.add_edge(1, Orientation::Forward, 2, Orientation::Forward)?;\ngraph.add_edge(1, Orientation::Forward, 3, Orientation::Forward)?;\ngraph.add_edge(2, Orientation::Forward, 4, Orientation::Forward)?;\ngraph.add_edge(3, Orientation::Forward, 4, Orientation::Forward)?;\n\n// Finalize and analyze\ngraph.finalize();\nprintln!(\"Graph has {} vertices and {} edges\",\n         graph.vertex_count(), graph.edge_count());\n```\n\n### Example: Load and analyze a GFA file\n\n```rust\nuse povu::PovuGraph;\n\n// Load from GFA\nlet graph = PovuGraph::load(\"graph.gfa\")?;\n\n// Query topology\nlet vertices = graph.vertices()?;\nlet edges = graph.edges()?;\nlet paths = graph.paths()?;\n\n// Analyze for variation\nlet analysis = graph.analyze()?;\nprintln!(\"Found {} variation regions\", analysis.flubble_count());\n```\n\nFor more examples, see the `povu-rs/examples/` directory.\n\n## Building povu\n\nPrerequisites:\n- CMake (3.0+ recommended)\n- C compiler (e.g., GCC or Clang)\n\n**Clone the repository:**\n```bash\ngit clone https://github.com/pangenome/povu.git\ncd povu\n```\n\n**Standard build:**\n```bash\ncmake -H. -Bbuild && cmake --build build -- -j 3\n```\n\nThe binary will be in `./bin/povu`\n\n### Installing with Guix\n\n**Enter Guix development shell:**\n```bash\nguix shell -C -N -D -f guix.scm\n```\n\n**Build inside the shell:**\n```bash\ncmake -H. -Bbuild -D CMAKE_BUILD_TYPE=Release && cmake --build build -- -j 3\n```\n\n### Building specific target\n\nBuilding only the povu library\n\n```\ncmake -H. -DCMAKE_BUILD_TYPE=Debug -Bbuild && cmake --build build --target povulib -- -j 8\n```\n\nBuilding only the povu binary\n\n```\ncmake -H. -DCMAKE_BUILD_TYPE=Debug -Bbuild && cmake --build build --target povu -- -j 8\n```\n\n### Development\n\nTo compile povu with debug symbols and address sanitizer:\n\n```bash\ncmake -DCMAKE_BUILD_TYPE=Debug -DUSE_SANITIZER=address -H. -Bbuild && cmake --build build -- -j 3\n```\n\nRunning tests\n\n1. Configure the build with testing enabled:\n\n```\ncmake -Bbuild -DPOVU_ENABLE_TESTING=ON -DCMAKE_BUILD_TYPE=Debug\n```\n\n2. Build the project:\n```\ncmake --build build\n```\n\n3. Run tests with CTest\n\n```\nctest --test-dir build\n```\n\n## Repository Structure\n\n```\npovu/\n├── bin/              # Compiled binaries (povu CLI)\n├── docs/             # Documentation\n├── include/          # C++ headers\n│   └── povu/        # Public API headers\n├── src/             # C++ implementation\n│   └── povu/        # Core library sources\n├── tests/           # C++ test data\n├── povu-rs/         # Rust bindings\n│   ├── src/         # Rust high-level API\n│   ├── povu-ffi/    # C FFI bridge layer\n│   │   ├── povu_ffi.h     # C API header\n│   │   └── povu_ffi.cpp   # C++ implementation\n│   ├── examples/    # Rust usage examples\n│   └── tests/       # Rust integration tests\n└── CMakeLists.txt   # Build configuration\n```\n\n### Key Components\n\n- **C++ Core** (`src/`, `include/`): The main Povu library implementing the variation detection algorithms\n- **CLI Tool** (`bin/`): Command-line interface for gfa2vcf, decompose, call, and info subcommands\n- **Rust Bindings** (`povu-rs/`): Safe Rust wrappers around the C++ library\n  - High-level API for graph construction, querying, and analysis\n  - C FFI bridge providing a stable interface between C++ and Rust\n  - Comprehensive test suite ensuring correctness\n\nThe Rust bindings live alongside the C++ code following the pattern used by many projects that provide multiple language interfaces (e.g., ripgrep, numpy, node.js).\n\n## Name\n\nThe etymology of the name is rooted in profound philosophy 🤔. \"Povu,\" is [Kiswahili](https://en.wikipedia.org/wiki/Swahili_language) for \"foam.\" Foam, by nature, comprises countless flubbles.\n",1780241992267]