obitools4/autodoc/docmd/pkg/obisuffix/suffix_array.md

# Suffix Array Implementation for Biological Sequences

This Go package (`obisuffix`) provides a suffix array data structure tailored for biological sequence analysis. It supports efficient lexicographic sorting and common-prefix computation over all suffixes of a set of sequences.

## Core Types

- **`Suffix`**: Represents one suffix by storing the sequence index (`Idx`) and starting position (`Pos`).  
- **`SuffixArray`**: Holds a collection of `Suffix`, the original sequences (`Sequences`), and cached common-prefix lengths (`Common`).  

## Key Functions

- **`BuildSuffixArray(data)`**: Constructs a suffix array by enumerating *all* suffixes from all input sequences, then sorts them lexicographically using a custom comparator (`SuffixLess`).  
- **`CommonSuffix()`**: Computes the length of shared prefix between each adjacent pair in the sorted suffix array (i.e., `LCP`-like values), caching results for reuse.  
- **`String()`**: Returns a human-readable table with columns: `Common`, sequence index, position, and suffix string.  

## Semantic Features

- **Lexicographic ordering**: Suffixes are sorted by their nucleotide/amino-acid content; ties break first by shorter length, then lower index, finally earlier position.  
- **Efficiency**: Avoids redundant comparisons via memoization of `Common` values and stable sorting.  
- **Biological relevance**: Designed for use with `obiseq.BioSequenceSlice`, supporting DNA, RNA, or protein sequences.  
- **Transparency**: The `String()` method enables quick inspection of suffix relationships and overlaps.

This structure is foundational for tasks like repeat detection, alignment-free comparison, or pattern mining in multi-sequence datasets.