obitools4/autodoc/docmd/pkg/obidist/dist_matrix_test.md

# `obidist` Package: Semantic Feature Overview

The `obidist` Go package provides two core data structures for managing **distance** and **similarity matrices**, with built-in guarantees suitable for scientific computing (e.g., clustering, phylogenetics). Key features include:

- **`DistMatrix`**: A symmetric `n×n` matrix representing pairwise distances, where:
  - Diagonal entries are *always* `0.0` (self-distance).
  - Off-diagonals obey symmetry: `dist(i, j) == dist(j, i)`.
  - Automatic enforcement via dedicated `Set()`/`Get()` methods.
  
- **`SimilarityMatrix`**: A symmetric matrix where:
  - Diagonal entries are *always* `1.0`.
  - Off-diagonals represent similarity scores (e.g., between `0` and `1`, though not enforced).
  - Symmetry is similarly guaranteed.

Both matrix types support:
- **Optional labels**: Associate human-readable identifiers (e.g., sample names) with rows/columns.
- **Safe bounds checking**: Panics on out-of-range access (tested via `defer/recover`).
- **Deep copy support**: Ensures isolation between original and copied instances.
- **Utility methods**:
  - `MinDistance()` / `MaxDistance()`: Return extremal values and their indices.
  - `GetRow(i)`: Retrieve a full row as a slice (symmetric copy).
  - `ToFullMatrix()`: Export the matrix as an immutable 2D slice.

Edge cases are rigorously handled:
- Empty (`n=0`) and singleton (`n=1`) matrices return `(0.0, -1, -1)` for min/max.
- Label mutations do not affect internal state via defensive copying.

All behaviors are validated through comprehensive unit tests, emphasizing correctness and robustness.