User Guide

This user guide provides comprehensive coverage of genogrove’s functionality, from reading genomic files to building complex data structures and queries.

Prerequisites

Before starting, ensure you have:

• Installed genogrove (see genogrove for installation instructions)

• A C++20 compatible compiler (GCC 13+, Clang 16+, Apple Clang 15+)

• Basic familiarity with genomic file formats (BED, GFF/GTF)

Guide Contents

• Installation
  • Prerequisites
  • Building from Source
  • Using in Your Project
    • CMake Integration
    • Manual Integration
  • Verify Installation
  • Development Build
  • Troubleshooting
  • Next Steps
• Reading Genomic Files (I/O)
  • Reader Ownership
  • Automatic File Type Detection
  • Iterator Equality Contract
  • Error Handling
    • Lenient Mode
    • Error Message Lifecycle
    • Zero-Record Inputs
  • Coordinate Semantics
  • BED Files
    • Mixed BED Formats
    • BED Entry Fields
  • GFF/GTF Files
    • GFF Entry Fields
    • Attribute Access
    • GTF Quoted Semicolons
    • GTF Validation
    • Convenience Methods
  • BAM/SAM Files
    • Filtering Options
    • SAM Entry Fields
    • CIGAR Operations
    • Tag Access
    • Header Access
    • Convenience Methods
  • FASTA / FASTQ Files
    • Streaming: fasta_reader
    • FASTA Entry Fields
    • Indexed Access: fasta_index
• Working with Data Types
  • Common Interface
  • Intervals
  • Genomic Coordinates
  • Keys and Associated Data
  • Numeric
  • K-mer
    • Key
    • Registry
• Grove
  • Key Types and the key_type_base Concept
  • Creating a Grove
  • Ownership Semantics
  • Accessing Indices
  • Inserting Data
  • Bulk Insertion
  • Removing Keys
    • Reclaiming removed-key storage (compact)
  • Querying Intervals
  • Flanking-Key Queries
    • Filtering by a Predicate
• Serialization
  • Basic Usage
  • How It Works
  • Combined Persistence with Registry
  • Custom Key Type Serialization
  • Custom Data Type Serialization
    • Option 1: Member methods
    • Option 2: Specialize serialization_traits
    • What works automatically
  • Source Stream Must Be Seekable for Concatenated Payloads
  • Important Notes
• Complete Examples
  • Processing BED Files
  • Processing GFF/GTF Files
  • Building Transcript Graphs
• Performance Optimization
  • Tips for Optimal Performance
    • Choose Appropriate Tree Order
    • Use Sorted Insertion for Pre-sorted Data
    • Use Bulk Insertion for Large Datasets
    • Organize by Chromosome
  • Compression Support
    • Choosing the Right Compression Format
  • Memory Management
    • Efficient Memory Usage
    • Graph Overlay Considerations
  • Serialization
  • Query Optimization
    • Chromosome-Specific Queries
    • Result Processing
  • Benchmarking
  • Best Practices Summary

Next Steps

• Explore the full API Reference for detailed API documentation

• Check the examples directory in the repository

• Learn about advanced features in the project wiki

• Join the community discussions on GitHub