obitools4/autodoc/docmd/pkg_obingslibrary.md

# `obingslibrary`: High-Throughput Sequencing Demultiplexing Library

`obingslibrary` is a Go package for **sample assignment in amplicon-based NGS workflows**, using dual-indexed barcodes flanked by PCR primers. It enables robust, configurable demultiplexing of sequencing reads—even in the presence of errors or indels—by matching primer–tag patterns and assigning samples via tag lookup.

---

## Core Functionalities

### 1. **Primer & Tag Configuration**
- `Marker`: Defines a primer pair (forward/reverse), including:
  - Primer sequences (`Forward`, `Reverse`) and reverse-complement variants.
  - Tag specifications: lengths, spacers (e.g., `N` or fixed nucleotides), delimiters.
  - Mismatch/indel tolerance per direction (`SetAllowedMismatch`, `SetTagIndels`).
- **Compilation**:  
  - `Compile()` / `Compile2()`: Builds internal pattern indexes (via `obiapat.ApatPattern`) for fast, error-tolerant matching.
  - Supports `"strict"`, `"hamming"` (substitutions only), or `"indel"` (Levenshtein) matching modes.

### 2. **Sequence Matching & Demultiplexing**
- `Match(sequence)`: Scans a `BioSequence` for valid primer bindings:
  - Prioritizes forward-primer detection; falls back to reverse orientation.
  - Returns `DemultiplexMatch` with:
    - Primer positions, mismatches, orientation (`IsDirect`).
    - Barcode coordinates (`BarcodeStart`, `BarcodeEnd`) and validity flag.
- **Primer dimer detection**: If `BarcodeStart > BarcodeEnd`, the read is flagged as invalid.

### 3. **Tag Extraction & Annotation**
- `ExtractBarcode(sequence, inplace)`:
  - Extracts the barcode region between forward/reverse primers.
  - Reverse-complements if read is in reverse orientation (`IsDirect == false`).
  - Annotates the sequence with:
    - Primer names, positions, mismatches.
    - Sample/experiment info (if tag assignment succeeds).
    - Error messages (`Unassigned`, `NoMatch`, etc.).
- **Tag extraction strategies**:
  - `Fixed`: Fixed-length tags.
  - `Delimited`: Tags flanked by exact delimiters (e.g., `"NN"`).
  - `Rescue`: Tolerates indels in delimiter or tag boundaries.

### 4. **Sample Registration & Lookup**
- `GetPCR(tagPair)`: Retrieves or registers a new PCR reaction indexed by tag pair (case-insensitive).
- `NGSLibrary.Markers`: Map of primer pairs → `Marker` objects.
  - Lazy initialization via `GetMarker()` for new primers.

### 5. **Validation & Consistency Checks**
- `CheckTagLength()`: Ensures all registered tags have uniform length per direction.
- `CheckPrimerUnicity()`: Validates no primer is reused across markers; prevents self-complementary pairs.

### 6. **Batch Processing & Parallelism**
- `ExtractBarcodeSlice(sequences, options)`: Processes a slice of reads.
  - Configurable via `Options` (fluent API):
    - Mismatch/indel budgets.
    - Error handling (`discardErrors`, `OptionUnidentified`).
    - Parallel workers, batch size.
- `ExtractBarcodeSliceWorker()`: Returns a reusable worker for concurrent pipelines.

### 7. **Distance Metrics**
- `Hamming(s1, s2)`: Counts mismatches between equal-length strings.
- `Levenshtein(s1, s2)`: Computes edit distance (supports indels).

### 8. **Sample Identification**
- `TagExtractor`: Extracts forward/reverse tags from primer-flanked regions.
- `SampleIdentifier`:
  - Matches extracted tags to known samples using configured strategy (`strict`, `hamming`, or `indel`).
  - Returns best-matching sample, distance, and proposed tags.

---

## Design Highlights
- **Memory-efficient**: Uses reference-counted sequences (`Recycle()`).
- **Error-aware**: Rich error propagation (stored in `DemultiplexMatch.Error` or annotations).
- **Flexible tag design**: Supports fixed, delimited (exact), and indel-resilient tags.
- **Extensible via options**: Functional setters for clean, testable configuration.

---

## Use Case
Ideal for **metabarcoding or targeted amplicon sequencing**, where samples are multiplexed using unique dual barcodes. Ensures high specificity (unique tag pairs) and sensitivity (error-tolerant matching).