obitools4/autodoc/docmd/pkg_obialign.md

# `obialign` Package: Semantic Overview

The `obialign` package delivers high-performance, memory-efficient utilities for biological sequence alignment within the OBITools4 ecosystem. It targets amplicon and metagenomic data processing, emphasizing speed, numerical stability, and scalability.

---

## Core Functionalities

### 1. **Sequence Encoding & Decoding**
- `Encode4bits`: Converts IUPAC nucleotides (including ambiguous codes like R, Y, N) into compact 4-bit representations.  
- Supports bitwise operations for rapid comparison (e.g., via `_FourBitsBaseCode`).  
- Handles gaps (`.`/`-`) and invalid characters as `0b0000`.

### 2. **Alignment Scoring & Probability Models**
- `_MatchRatio`, `_NucPartMatch`: Compute match likelihoods using bitwise overlap of encoded bases.  
- Log-space helpers (`_Logaddexp`, `_Logdiffexp`) ensure numerical stability in probabilistic scoring.  
- Quality-aware scores via precomputed matrices (`_NucScorePartMatch{Match,Mismatch}`), incorporating Phred scores and base composition priors.

### 3. **Dynamic Programming (DP) Backtracking**
- `_Backtracking`: Reconstructs optimal alignment paths from precomputed matrices.  
  - Encodes diagonal runs and gap segments as alternating `(offset, length)` pairs.
- Optimized for batch reuse of path buffers and minimal allocations.

### 4. **Longest Common Subsequence (LCS) with Error Tolerance**
- `FastLCSEGFScore`, `FastLCSScore`: Compute LCS under bounded error (`maxError`) and optional end-gap-free mode.  
  - Uses diagonal banding for efficiency.
- Designed for rapid similarity filtering (e.g., UMI/OTU clustering).

### 5. **Single-Edit Distance Detection**
- `D1Or0`: Determines if two sequences are identical or differ by exactly one edit (substitution/indel).  
  - Early termination on length mismatch or multiple divergences.  
  - Critical for error correction and dereplication.

### 6. **Local Pattern Matching**
- `LocatePattern`: Finds optimal approximate match of a short query (e.g., primer) in longer sequence.  
  - End-gap-free alignment, using DP with mismatch/gap penalty `-1`.  
  - Returns start/end positions and error count.

### 7. **Paired-End Read Alignment**
- `PEAlign`, `_FillMatrixPeLeftAlign`, etc.: Global alignment of paired-end reads with affine gap penalties.  
  - Supports three modes: `PELeftAlign`, `PERightAlign`, and `PECenterAlign` (for overlaps).  
  - Integrates k-mer pre-screening (`obikmer.Index4mer`) for fast overlap estimation.  
  - Quality-aware scoring via `_PairingScorePeAlign`.

### 8. **Consensus & Alignment Reconstruction**
- `BuildAlignment`, `_BuildAlignment`: Reconstruct aligned sequences from DP path, reusing buffers.  
- `BuildQualityConsensus`: Generates consensus with quality-aware base selection:  
  - Mismatches resolved by higher-quality call or IUPAC ambiguity.  
  - Optional mismatch statistics recording.

### 9. **Memory & Performance Optimization**
- `PEAlignArena`: Reusable memory arena for matrices, paths, and buffers.  
  - Reduces GC pressure in high-throughput pipelines.
- Compact `uint64` encoding for scores, path lengths, and flags (`encodeValues`, `_incscore`).  
  - Enables fast comparisons during DP.

---

## Design Principles

- **IUPAC-aware**: Handles ambiguous nucleotides via `obiseq.SameIUPACNuc`.  
- **Thread-safe initialization**: `_InitDNAScoreMatrix` uses mutex guards.  
- **No allocations in hot paths**: Buffers reused across calls (arena pattern).  
- **End-gap flexibility**: Critical for read merging and primer trimming.

---

## Use Cases

| Functionality | Application |
|---------------|-------------|
| `FastLCSEGFScore`, `D1Or0` | OTU/ASV clustering, UMI deduplication |
| `LocatePattern`, `PEAlign` | Primer trimming, read merging in metabarcoding |
| `BuildQualityConsensus`, `_Backtracking` | Consensus generation post-merge |

Designed for integration into large-scale NGS pipelines—especially where speed, memory footprint, and numerical robustness are critical.