dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/evaluation/_shared.py

@@ -0,0 +1,288 @@
+"""Shared bounded primitives for DNA evaluation implementations."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import TypeAlias, cast
+
+from dnakit.alignment import AlignmentConfig, align_pairwise
+from dnakit.core import (
+    DNA,
+    DNARecord,
+    DNASequence,
+    DNASet,
+    ImplementationInfo,
+    ImplementationLabel,
+    Issue,
+    IssueSeverity,
+    Provenance,
+    ReferenceInfo,
+)
+from dnakit.core._json import FrozenDict, to_json_compatible
+from dnakit.exceptions import ConfigurationError, UnsupportedGapOperationError
+from dnakit.similarity import edit_distance, exact_similarity, kmer_similarity
+
+from .config import EvaluationLimits, PairSimilarityMethod
+from .results import EvaluationEntry, EvaluationReport, ReferenceLibrary
+
+EvaluationInput: TypeAlias = DNA | DNASequence | DNARecord | DNASet | Iterable[DNARecord]
+
+
+@dataclass(frozen=True, slots=True)
+class InputItem:
+    sequence: DNASequence
+    subject_id: str
+    record: DNARecord | None
+
+
+def provenance(*, reference: ReferenceLibrary | None = None) -> Provenance:
+    reference_info = None
+    if reference is not None:
+        reference_info = ReferenceInfo(
+            reference.name,
+            version=reference.version,
+            date=reference.date,
+            checksum=reference.digest,
+            filters=reference.filters,
+        )
+    return Provenance(
+        implementation=ImplementationInfo(label=ImplementationLabel.NATIVE),
+        reference=reference_info,
+    )
+
+
+def issue(code: str, severity: IssueSeverity, message: str, **details: object) -> Issue:
+    return Issue(code, severity, message, details=details)
+
+
+def materialize_input(value: EvaluationInput, *, limits: EvaluationLimits) -> tuple[InputItem, ...]:
+    if isinstance(value, DNA) and value.is_single:
+        record = value.record
+        items: tuple[InputItem, ...] = (InputItem(record.sequence, record.id, record),)
+    elif isinstance(value, DNASequence):
+        items = (InputItem(value, "sequence", None),)
+    elif isinstance(value, DNARecord):
+        items = (InputItem(value.sequence, value.id, value),)
+    else:
+        source = value.records if isinstance(value, (DNA, DNASet)) else value
+        try:
+            iterator = iter(source)
+        except TypeError as exc:
+            raise ConfigurationError(
+                "Evaluation input must be a DNASequence, DNARecord, DNASet, or record iterable.",
+                code="INVALID_EVALUATION_INPUT",
+            ) from exc
+        collected: list[InputItem] = []
+        for index, record in enumerate(iterator):
+            if not isinstance(record, DNARecord):
+                raise ConfigurationError(
+                    "Evaluation collections must contain DNARecord objects.",
+                    code="INVALID_EVALUATION_RECORD",
+                    context={"input_index": index, "type": type(record).__name__},
+                )
+            if index >= limits.max_records:
+                raise ConfigurationError(
+                    "Evaluation input exceeds max_records.",
+                    code="EVALUATION_RECORD_LIMIT",
+                    context={
+                        "record_count_lower_bound": index + 1,
+                        "max_records": limits.max_records,
+                    },
+                )
+            collected.append(InputItem(record.sequence, record.id, record))
+        items = tuple(collected)
+    if len(items) > limits.max_records:
+        raise ConfigurationError(
+            "Evaluation input exceeds max_records.",
+            code="EVALUATION_RECORD_LIMIT",
+            context={"record_count": len(items), "max_records": limits.max_records},
+        )
+    total_symbols = sum(item.sequence.symbol_length for item in items)
+    if total_symbols > limits.max_total_symbols:
+        raise ConfigurationError(
+            "Evaluation input exceeds max_total_symbols.",
+            code="EVALUATION_SYMBOL_LIMIT",
+            context={"total_symbols": total_symbols, "max_total_symbols": limits.max_total_symbols},
+        )
+    return items
+
+
+def require_nonempty(items: tuple[InputItem, ...], operation: str) -> None:
+    if not items:
+        raise ConfigurationError(
+            f"{operation} requires at least one record.", code="EMPTY_EVALUATION_DATASET"
+        )
+
+
+def pair_count(left_size: int, right_size: int | None = None) -> int:
+    return left_size * (left_size - 1) // 2 if right_size is None else left_size * right_size
+
+
+def enforce_pair_limit(count: int, limits: EvaluationLimits) -> None:
+    if count > limits.max_pairwise_comparisons:
+        raise ConfigurationError(
+            "Evaluation workload exceeds max_pairwise_comparisons.",
+            code="EVALUATION_PAIRWISE_LIMIT",
+            context={"pairwise_comparisons": count, "limit": limits.max_pairwise_comparisons},
+        )
+
+
+def require_pairwise_compatible(sequence: DNASequence, *, role: str) -> None:
+    if sequence.is_gapped:
+        raise UnsupportedGapOperationError(
+            "Pairwise evaluation does not silently omit or bridge Gap objects.",
+            code="EVALUATION_GAP_UNSUPPORTED",
+            context={"role": role},
+        )
+
+
+def pair_similarity(
+    left: DNARecord,
+    right: DNARecord,
+    *,
+    method: PairSimilarityMethod,
+    k: int,
+    canonical: bool,
+    max_alignment_cells: int,
+) -> tuple[float, float | None]:
+    require_pairwise_compatible(left.sequence, role="left")
+    require_pairwise_compatible(right.sequence, role="right")
+    if method == "exact":
+        return exact_similarity(left, right).value, 1.0
+    if method == "identity":
+        result = align_pairwise(
+            left,
+            right,
+            config=AlignmentConfig(mode="global", max_cells=max_alignment_cells),
+        )
+        return (1.0 if result.identity is None else result.identity), min(
+            result.query_coverage, result.target_coverage
+        )
+    if method == "edit":
+        distance_result = edit_distance(left, right, max_cells=max_alignment_cells)
+        denominator = max(left.sequence.symbol_length, right.sequence.symbol_length)
+        return (1.0 if denominator == 0 else 1.0 - distance_result.distance / denominator), None
+    if left.sequence.symbol_length < k or right.sequence.symbol_length < k:
+        return (1.0 if left.sequence.symbols == right.sequence.symbols else 0.0), None
+    return kmer_similarity(left, right, k=k, canonical=canonical).value, None
+
+
+def aggregate_numeric(entries: tuple[EvaluationEntry, ...], metric: str) -> FrozenDict:
+    values = tuple(
+        float(value)
+        for entry in entries
+        if (value := entry.metrics.get(metric)) is not None
+        and not isinstance(value, bool)
+        and isinstance(value, (int, float))
+    )
+    return FrozenDict(
+        {
+            "count": len(values),
+            "mean": math.fsum(values) / len(values) if values else None,
+            "minimum": min(values) if values else None,
+            "maximum": max(values) if values else None,
+        }
+    )
+
+
+def report(
+    *,
+    name: str,
+    method: str,
+    version: str,
+    parameters: Mapping[str, object],
+    metrics: Mapping[str, object],
+    entries: Iterable[EvaluationEntry] = (),
+    issues: Iterable[Issue] = (),
+    reference: ReferenceLibrary | None = None,
+) -> EvaluationReport:
+    return EvaluationReport(
+        name,
+        method,
+        version,
+        FrozenDict(cast(Mapping[str, object], to_json_compatible(parameters))),
+        FrozenDict(cast(Mapping[str, object], to_json_compatible(metrics))),
+        tuple(entries),
+        provenance(reference=reference),
+        tuple(issues),
+    )
+
+
+def sequence_digest_payload(records: DNASet) -> dict[str, object]:
+    return {
+        "schema": "dnakit.reference-library-sequences.v1",
+        "records": [
+            {
+                "id": record.id,
+                "parts": [
+                    part
+                    if isinstance(part, str)
+                    else {
+                        "gap": {
+                            "length": part.length,
+                            "kind": part.kind.value,
+                            "crossable": part.crossable,
+                            "evidence": part.evidence,
+                            "metadata": part.metadata,
+                        }
+                    }
+                    for part in record.sequence.parts
+                ],
+                "alphabet": record.sequence.alphabet.value,
+                "topology": record.sequence.topology.value,
+                "strandedness": record.sequence.strandedness.value,
+            }
+            for record in records
+        ],
+    }
+
+
+def digest_json(value: object) -> str:
+    payload = json.dumps(
+        to_json_compatible(value),
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    ).encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()
+
+
+def record_for(item: InputItem) -> DNARecord:
+    return item.record or DNARecord(item.sequence, item.subject_id)
+
+
+def mean(values: Iterable[float]) -> float | None:
+    materialized = tuple(values)
+    return math.fsum(materialized) / len(materialized) if materialized else None
+
+
+def as_float(mapping: Mapping[str, object], key: str) -> float:
+    value = mapping[key]
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ConfigurationError("Internal evaluation metric is not numeric.")
+    return float(value)
+
+
+__all__ = [
+    "EvaluationInput",
+    "InputItem",
+    "aggregate_numeric",
+    "as_float",
+    "digest_json",
+    "enforce_pair_limit",
+    "issue",
+    "materialize_input",
+    "mean",
+    "pair_count",
+    "pair_similarity",
+    "provenance",
+    "record_for",
+    "report",
+    "require_nonempty",
+    "sequence_digest_payload",
+]

dnakit/evaluation/collection.py

@@ -0,0 +1,270 @@
+"""Collection uniqueness, diversity, and redundancy evaluation."""
+
+from __future__ import annotations
+
+from dnakit.core import DNARecord
+from dnakit.datasets import (
+    ClusterConfig,
+    IUPACDeduplicationConfig,
+    cluster_sequences,
+    deduplicate,
+    deduplicate_iupac,
+)
+
+from ._shared import (
+    EvaluationInput,
+    enforce_pair_limit,
+    materialize_input,
+    mean,
+    pair_count,
+    pair_similarity,
+    record_for,
+    report,
+)
+from .config import DiversityEvaluationConfig, UniquenessEvaluationConfig
+from .results import EvaluationReport
+
+
+def _records(value: EvaluationInput, config: UniquenessEvaluationConfig) -> tuple[DNARecord, ...]:
+    return tuple(record_for(item) for item in materialize_input(value, limits=config.limits))
+
+
+def evaluate_uniqueness(
+    value: EvaluationInput,
+    *,
+    config: UniquenessEvaluationConfig | None = None,
+) -> EvaluationReport:
+    """Compute non-duplicate fraction under one explicitly configured equivalence."""
+
+    resolved = UniquenessEvaluationConfig() if config is None else config
+    if not isinstance(resolved, UniquenessEvaluationConfig):
+        raise TypeError("config must be UniquenessEvaluationConfig or None.")
+    records = _records(value, resolved)
+    if resolved.equivalence == "iupac":
+        iupac_result = deduplicate_iupac(
+            records,
+            config=IUPACDeduplicationConfig(
+                max_records=resolved.limits.max_records,
+                max_pairwise_comparisons=resolved.limits.max_pairwise_comparisons,
+            ),
+        )
+        groups = tuple(group.member_ids for group in iupac_result.groups)
+        unique_count = iupac_result.output_count
+        comparisons = iupac_result.pairwise_comparison_count
+        strategy = iupac_result.grouping_strategy
+    elif resolved.equivalence == "approximate":
+        cluster_method = (
+            "identity" if resolved.approximate_method == "exact" else resolved.approximate_method
+        )
+        cluster_result = cluster_sequences(
+            records,
+            config=ClusterConfig(
+                method=cluster_method,
+                threshold=1.0 if resolved.approximate_method == "exact" else resolved.threshold,
+                k=resolved.k,
+                canonical=resolved.canonical,
+                max_records=resolved.limits.max_records,
+                max_pairwise_comparisons=resolved.limits.max_pairwise_comparisons,
+                max_alignment_cells=resolved.limits.max_alignment_cells,
+            ),
+        )
+        groups = tuple(cluster.member_ids for cluster in cluster_result.clusters)
+        unique_count = len(cluster_result.clusters)
+        comparisons = cluster_result.pairwise_comparison_count
+        strategy = cluster_result.clustering_strategy
+    else:
+        dedup_result = deduplicate(records, equivalence=resolved.equivalence)
+        groups = tuple(group.member_ids for group in dedup_result.groups)
+        unique_count = len(dedup_result.groups)
+        comparisons = 0
+        strategy = "hash-equivalence-groups"
+    duplicate_groups = tuple(group for group in groups if len(group) > 1)
+    total = len(records)
+    score = unique_count / total if total else 1.0
+    return report(
+        name="uniqueness",
+        method=f"{resolved.equivalence}-equivalence",
+        version="eval-uniqueness-v1",
+        parameters={
+            "equivalence": resolved.equivalence,
+            "approximate_method": resolved.approximate_method,
+            "threshold": resolved.threshold,
+            "k": resolved.k,
+            "canonical": resolved.canonical,
+            "grouping_strategy": strategy,
+            "limits": resolved.limits,
+        },
+        metrics={
+            "score": score,
+            "uniqueness_score": score,
+            "record_count": total,
+            "unique_count": unique_count,
+            "duplicate_record_count": total - unique_count,
+            "duplicate_group_count": len(duplicate_groups),
+            "groups": groups,
+            "duplicate_groups": duplicate_groups,
+            "pairwise_comparison_count": comparisons,
+        },
+    )
+
+
+def _similarity_state(
+    records: tuple[DNARecord, ...], config: DiversityEvaluationConfig
+) -> tuple[tuple[tuple[float, ...], ...], int]:
+    comparisons = pair_count(len(records))
+    enforce_pair_limit(comparisons, config.limits)
+    matrix = [
+        [1.0 if left == right else 0.0 for right in range(len(records))]
+        for left in range(len(records))
+    ]
+    for left in range(len(records)):
+        for right in range(left + 1, len(records)):
+            similarity, _ = pair_similarity(
+                records[left],
+                records[right],
+                method=config.method,
+                k=config.k,
+                canonical=config.canonical,
+                max_alignment_cells=config.limits.max_alignment_cells,
+            )
+            matrix[left][right] = matrix[right][left] = similarity
+    return tuple(tuple(row) for row in matrix), comparisons
+
+
+def _component_count(matrix: tuple[tuple[float, ...], ...], threshold: float) -> int:
+    parents = list(range(len(matrix)))
+
+    def find(value: int) -> int:
+        while parents[value] != value:
+            parents[value] = parents[parents[value]]
+            value = parents[value]
+        return value
+
+    for left in range(len(matrix)):
+        for right in range(left + 1, len(matrix)):
+            if matrix[left][right] >= threshold:
+                left_root, right_root = find(left), find(right)
+                if left_root != right_root:
+                    parents[right_root] = left_root
+    return len({find(index) for index in range(len(matrix))})
+
+
+def evaluate_diversity(
+    value: EvaluationInput,
+    *,
+    config: DiversityEvaluationConfig | None = None,
+) -> EvaluationReport:
+    """Report exhaustive mean distance, nearest-neighbor distance, and cluster coverage."""
+
+    resolved = DiversityEvaluationConfig() if config is None else config
+    if not isinstance(resolved, DiversityEvaluationConfig):
+        raise TypeError("config must be DiversityEvaluationConfig or None.")
+    items = materialize_input(value, limits=resolved.limits)
+    records = tuple(record_for(item) for item in items)
+    matrix, comparisons = _similarity_state(records, resolved)
+    distances = tuple(
+        1.0 - matrix[left][right]
+        for left in range(len(records))
+        for right in range(left + 1, len(records))
+    )
+    nearest_distances = (
+        tuple(
+            min(1.0 - matrix[index][other] for other in range(len(records)) if other != index)
+            for index in range(len(records))
+        )
+        if len(records) > 1
+        else ()
+    )
+    cluster_count = _component_count(matrix, resolved.cluster_threshold)
+    cluster_coverage = cluster_count / len(records) if records else 1.0
+    mean_distance = mean(distances)
+    mean_nearest = mean(nearest_distances)
+    score = mean_nearest if mean_nearest is not None else (1.0 if len(records) <= 1 else 0.0)
+    return report(
+        name="diversity",
+        method="exhaustive-pair-distance-and-threshold-components",
+        version="eval-diversity-v1",
+        parameters={
+            "similarity_method": resolved.method,
+            "distance_definition": "1 - pair similarity",
+            "k": resolved.k,
+            "canonical": resolved.canonical,
+            "cluster_threshold": resolved.cluster_threshold,
+            "cluster_strategy": "connected-components-of-threshold-graph",
+            "short_k_policy": "literal equality when either sequence is shorter than k",
+            "topology_policy": "linearized at stored origin; no circular rotation",
+            "singleton_policy": "score=1; pair metrics undefined",
+            "limits": resolved.limits,
+        },
+        metrics={
+            "score": score,
+            "record_count": len(records),
+            "mean_pair_distance": mean_distance,
+            "mean_nearest_neighbor_distance": mean_nearest,
+            "minimum_nearest_neighbor_distance": min(nearest_distances)
+            if nearest_distances
+            else None,
+            "cluster_count": cluster_count,
+            "cluster_coverage": cluster_coverage,
+            "pairwise_comparison_count": comparisons,
+        },
+    )
+
+
+def evaluate_redundancy(
+    value: EvaluationInput,
+    *,
+    config: DiversityEvaluationConfig | None = None,
+) -> EvaluationReport:
+    """Report exact, similarity-threshold, and cluster-level redundancy."""
+
+    resolved = DiversityEvaluationConfig() if config is None else config
+    if not isinstance(resolved, DiversityEvaluationConfig):
+        raise TypeError("config must be DiversityEvaluationConfig or None.")
+    items = materialize_input(value, limits=resolved.limits)
+    records = tuple(record_for(item) for item in items)
+    matrix, comparisons = _similarity_state(records, resolved)
+    exact_unique_count = len(deduplicate(records, equivalence="exact").groups)
+    near_pair_count = sum(
+        matrix[left][right] >= resolved.cluster_threshold
+        for left in range(len(records))
+        for right in range(left + 1, len(records))
+    )
+    total_pairs = pair_count(len(records))
+    cluster_count = _component_count(matrix, resolved.cluster_threshold)
+    exact_fraction = (len(records) - exact_unique_count) / len(records) if records else 0.0
+    cluster_fraction = (len(records) - cluster_count) / len(records) if records else 0.0
+    near_pair_fraction = near_pair_count / total_pairs if total_pairs else 0.0
+    score = (exact_fraction + near_pair_fraction + cluster_fraction) / 3.0
+    return report(
+        name="redundancy",
+        method="exact-near-pair-threshold-component-mean",
+        version="eval-redundancy-v1",
+        parameters={
+            "similarity_method": resolved.method,
+            "threshold": resolved.cluster_threshold,
+            "k": resolved.k,
+            "canonical": resolved.canonical,
+            "score_formula": (
+                "mean(exact_duplicate_fraction,near_pair_fraction,cluster_redundancy_fraction)"
+            ),
+            "short_k_policy": "literal equality when either sequence is shorter than k",
+            "topology_policy": "linearized at stored origin; no circular rotation",
+            "limits": resolved.limits,
+        },
+        metrics={
+            "score": score,
+            "record_count": len(records),
+            "exact_unique_count": exact_unique_count,
+            "exact_duplicate_fraction": exact_fraction,
+            "near_pair_count": near_pair_count,
+            "pair_count": total_pairs,
+            "near_pair_fraction": near_pair_fraction,
+            "cluster_count": cluster_count,
+            "cluster_redundancy_fraction": cluster_fraction,
+            "pairwise_comparison_count": comparisons,
+        },
+    )
+
+
+__all__ = ["evaluate_diversity", "evaluate_redundancy", "evaluate_uniqueness"]