dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/datasets/deduplicate.py

@@ -0,0 +1,303 @@
+"""Exact and reverse-complement-aware record deduplication."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Iterable
+from typing import TypeAlias
+
+from dnakit.core import DNARecord, DNASequence, DNASet, Gap, Topology
+from dnakit.core._json import JSONValue
+from dnakit.exceptions import ConfigurationError
+
+from ._metadata import metadata_value_key
+from .config import DedupEquivalence, DeduplicationConfig
+from .results import DedupAction, DedupGroup, DeduplicationResult, Orientation
+
+SequenceKey: TypeAlias = tuple[tuple[str | Gap, ...], object, object]
+EquivalenceKey: TypeAlias = SequenceKey | frozenset[SequenceKey] | tuple[str, object, object]
+
+
+def _least_rotation(symbols: str) -> tuple[str, int]:
+    """Return the lexicographically least rotation and its first offset."""
+
+    if not symbols:
+        return symbols, 0
+    length = len(symbols)
+    doubled = symbols + symbols
+    left, right, matched = 0, 1, 0
+    while left < length and right < length and matched < length:
+        left_symbol = doubled[left + matched]
+        right_symbol = doubled[right + matched]
+        if left_symbol == right_symbol:
+            matched += 1
+            continue
+        if left_symbol > right_symbol:
+            left += matched + 1
+            if left <= right:
+                left = right + 1
+        else:
+            right += matched + 1
+            if right <= left:
+                right = left + 1
+        matched = 0
+    best_offset = min(left, right)
+    return doubled[best_offset : best_offset + length], best_offset
+
+
+def _sequence_key(sequence: DNASequence) -> SequenceKey:
+    # Alphabet is deliberately omitted: ACGT content has the same identity
+    # whether its validated declaration is strict or IUPAC.
+    return (sequence.parts, sequence.topology, sequence.strandedness)
+
+
+def _equivalence_key(sequence: DNASequence, equivalence: DedupEquivalence) -> EquivalenceKey:
+    forward = _sequence_key(sequence)
+    if equivalence == "exact":
+        return forward
+    if equivalence in {"circular", "circular_reverse_complement"}:
+        if sequence.topology is not Topology.CIRCULAR:
+            raise ConfigurationError(
+                "Circular equivalence requires every sequence to declare circular topology.",
+                code="CIRCULAR_DEDUPLICATION_TOPOLOGY_REQUIRED",
+            )
+        if sequence.is_gapped:
+            raise ConfigurationError(
+                "Circular rotation equivalence does not support Gap objects.",
+                code="CIRCULAR_DEDUPLICATION_GAP_UNSUPPORTED",
+            )
+        canonical, _ = _least_rotation(sequence.symbols)
+        if equivalence == "circular_reverse_complement":
+            reverse, _ = _least_rotation(sequence.reverse_complement().symbols)
+            canonical = min(canonical, reverse)
+        return canonical, sequence.topology, sequence.strandedness
+    return frozenset((forward, _sequence_key(sequence.reverse_complement())))
+
+
+def _materialize(records: Iterable[DNARecord]) -> tuple[DNARecord, ...]:
+    try:
+        materialized = tuple(records)
+    except TypeError as exc:
+        raise ConfigurationError(
+            "records must be an iterable of DNARecord objects.",
+            code="INVALID_DATASET_RECORDS",
+        ) from exc
+    for index, record in enumerate(materialized):
+        if not isinstance(record, DNARecord):
+            raise ConfigurationError(
+                "Every dataset item must be a DNARecord.",
+                code="INVALID_DATASET_RECORD",
+                context={"input_index": index, "type": type(record).__name__},
+            )
+    return materialized
+
+
+def _quality_score(record: DNARecord) -> float:
+    quality = record.letter_annotations.get("phred_quality")
+    if not quality:
+        return float("-inf")
+    return sum(quality) / len(quality)
+
+
+def _representative_index(
+    members: tuple[int, ...], records: tuple[DNARecord, ...], policy: str
+) -> int:
+    if policy == "first":
+        return members[0]
+    if policy == "last":
+        return members[-1]
+    return max(members, key=lambda index: (_quality_score(records[index]), -index))
+
+
+def _conflict(
+    members: tuple[int, ...],
+    records: tuple[DNARecord, ...],
+    field: str | None,
+) -> tuple[bool, tuple[JSONValue, ...], int]:
+    if field is None:
+        return False, (), 0
+    values: list[JSONValue] = []
+    missing = 0
+    for index in members:
+        if field not in records[index].metadata:
+            missing += 1
+        else:
+            values.append(records[index].metadata[field])
+    unique_by_key = {metadata_value_key(value): value for value in values}
+    unique_values = tuple(unique_by_key[key] for key in sorted(unique_by_key, key=repr))
+    distinct_count = len(unique_values) + int(missing > 0)
+    return distinct_count > 1, unique_values, missing
+
+
+def _merge_metadata(representative: DNARecord, members: tuple[DNARecord, ...]) -> DNARecord:
+    merged: dict[str, object] = dict(representative.metadata)
+    keys = {key for member in members for key in member.metadata}
+    for key in sorted(keys):
+        present = [member.metadata[key] for member in members if key in member.metadata]
+        if not present:
+            continue
+        first_key = metadata_value_key(present[0])
+        if all(metadata_value_key(value) == first_key for value in present[1:]):
+            merged.setdefault(key, present[0])
+    return DNARecord(
+        representative.sequence,
+        representative.id,
+        description=representative.description,
+        features=representative.features,
+        metadata=merged,
+        letter_annotations=representative.letter_annotations,
+    )
+
+
+def _orientations(
+    representative: DNARecord,
+    members: tuple[int, ...],
+    records: tuple[DNARecord, ...],
+    equivalence: DedupEquivalence,
+) -> tuple[Orientation, ...]:
+    representative_key = _sequence_key(representative.sequence)
+    reverse_key = _sequence_key(representative.sequence.reverse_complement())
+    values: list[Orientation] = []
+    for index in members:
+        member_key = _sequence_key(records[index].sequence)
+        orientation: Orientation = "forward"
+        if equivalence == "reverse_complement" and member_key != representative_key:
+            if member_key != reverse_key:
+                raise AssertionError("Member does not match its reverse-complement group.")
+            orientation = "reverse_complement"
+        values.append(orientation)
+    return tuple(values)
+
+
+def _circular_transforms(
+    representative: DNARecord,
+    members: tuple[int, ...],
+    records: tuple[DNARecord, ...],
+    equivalence: DedupEquivalence,
+) -> tuple[tuple[Orientation, ...], tuple[int | None, ...]]:
+    if equivalence not in {"circular", "circular_reverse_complement"}:
+        return _orientations(representative, members, records, equivalence), ()
+    orientations: list[Orientation] = []
+    offsets: list[int | None] = []
+    for index in members:
+        sequence = records[index].sequence
+        forward, forward_offset = _least_rotation(sequence.symbols)
+        orientation: Orientation = "forward"
+        offset = forward_offset
+        if equivalence == "circular_reverse_complement":
+            reverse, reverse_offset = _least_rotation(sequence.reverse_complement().symbols)
+            if reverse < forward:
+                orientation = "reverse_complement"
+                offset = reverse_offset
+        orientations.append(orientation)
+        offsets.append(offset)
+    return tuple(orientations), tuple(offsets)
+
+
+def deduplicate(
+    records: Iterable[DNARecord],
+    *,
+    equivalence: DedupEquivalence = "exact",
+    config: DeduplicationConfig | None = None,
+) -> DeduplicationResult:
+    """Deduplicate normalized records while preserving a complete group audit."""
+
+    if equivalence not in {
+        "exact",
+        "reverse_complement",
+        "circular",
+        "circular_reverse_complement",
+    }:
+        raise ConfigurationError(
+            "Unknown deduplication equivalence.",
+            code="INVALID_DEDUPLICATION_EQUIVALENCE",
+            context={"equivalence": equivalence},
+        )
+    resolved = DeduplicationConfig() if config is None else config
+    if not isinstance(resolved, DeduplicationConfig):
+        raise ConfigurationError(
+            "config must be DeduplicationConfig or None.",
+            code="INVALID_DEDUPLICATION_CONFIG",
+        )
+    materialized = _materialize(records)
+    grouped: dict[Hashable, list[int]] = {}
+    for index, record in enumerate(materialized):
+        grouped.setdefault(_equivalence_key(record.sequence, equivalence), []).append(index)
+
+    output: list[DNARecord] = []
+    audit_groups: list[DedupGroup] = []
+    conflict_count = 0
+    for group_index, raw_members in enumerate(grouped.values()):
+        members = tuple(raw_members)
+        representative_index = _representative_index(
+            members, materialized, resolved.representative_policy
+        )
+        representative = materialized[representative_index]
+        orientations, rotation_offsets = _circular_transforms(
+            representative, members, materialized, equivalence
+        )
+        conflict, conflict_values, missing_count = _conflict(
+            members, materialized, resolved.conflict_field
+        )
+        if conflict:
+            conflict_count += 1
+            if resolved.conflict_policy == "error":
+                raise ConfigurationError(
+                    "A duplicate group contains conflicting metadata values.",
+                    code="DEDUPLICATION_METADATA_CONFLICT",
+                    context={
+                        "group_index": group_index,
+                        "member_ids": [materialized[index].id for index in members],
+                        "conflict_field": resolved.conflict_field,
+                    },
+                    hint="Choose drop_group, keep_representative, or keep_all explicitly.",
+                )
+        action: DedupAction = "deduplicated"
+        if conflict and resolved.conflict_policy == "drop_group":
+            action = "dropped"
+        elif conflict and resolved.conflict_policy == "keep_all":
+            action = "kept_all"
+            output.extend(materialized[index] for index in members)
+        else:
+            chosen = representative
+            if resolved.merge_metadata:
+                chosen = _merge_metadata(
+                    representative, tuple(materialized[index] for index in members)
+                )
+            output.append(chosen)
+        audit_groups.append(
+            DedupGroup(
+                group_index=group_index,
+                representative_id=representative.id,
+                member_ids=tuple(materialized[index].id for index in members),
+                orientations=orientations,
+                conflict=conflict,
+                conflict_values=conflict_values,
+                missing_conflict_value_count=missing_count,
+                action=action,
+                rotation_offsets=rotation_offsets,
+                rotation_offset_definition=(
+                    "zero-based left-rotation offset to the lexicographically least "
+                    "representation after the reported orientation"
+                    if equivalence in {"circular", "circular_reverse_complement"}
+                    else None
+                ),
+            )
+        )
+    dataset = DNASet(output)
+    return DeduplicationResult(
+        records=dataset,
+        groups=tuple(audit_groups),
+        equivalence=equivalence,
+        representative_policy=resolved.representative_policy,
+        conflict_field=resolved.conflict_field,
+        conflict_policy=resolved.conflict_policy,
+        merge_metadata=resolved.merge_metadata,
+        input_count=len(materialized),
+        output_count=len(dataset),
+        duplicate_count=len(materialized) - len(audit_groups),
+        conflicted_group_count=conflict_count,
+        removed_count=len(materialized) - len(dataset),
+    )
+
+
+__all__ = ["deduplicate"]

dnakit/datasets/evaluation.py

@@ -0,0 +1,244 @@
+"""Exhaustive bounded leakage detection and split-quality metrics."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+
+from dnakit.core import DNA, DNASet
+from dnakit.core._json import FrozenDict
+from dnakit.exceptions import ConfigurationError
+
+from ._advanced_shared import pair_similarity, validate_pairwise_sequences
+from ._metadata import metadata_value_key
+from .config import LeakageConfig
+from .results import (
+    LeakageEvent,
+    LeakageReport,
+    SplitAssignment,
+    SplitQualityResult,
+)
+
+
+def _validate_splits(
+    splits: Mapping[str, DNA | DNASet],
+) -> tuple[tuple[str, DNASet], ...]:
+    if not isinstance(splits, Mapping) or len(splits) < 2:
+        raise ConfigurationError("splits must map at least two names to DNA values.")
+    items = tuple(splits.items())
+    if any(
+        not isinstance(name, str) or not name.strip() or not isinstance(dataset, (DNA, DNASet))
+        for name, dataset in items
+    ):
+        raise ConfigurationError("Split names must be non-empty and values must be DNA.")
+    return tuple(
+        (name, dataset.dataset if isinstance(dataset, DNA) else dataset) for name, dataset in items
+    )
+
+
+def detect_leakage(
+    splits: Mapping[str, DNA | DNASet],
+    *,
+    config: LeakageConfig | None = None,
+) -> LeakageReport:
+    """Exhaustively compare every cross-split pair under hard record/pair/event limits."""
+
+    resolved = LeakageConfig() if config is None else config
+    if not isinstance(resolved, LeakageConfig):
+        raise ConfigurationError("config must be LeakageConfig.")
+    items = _validate_splits(splits)
+    total = sum(len(dataset) for _, dataset in items)
+    if total > resolved.max_records:
+        raise ConfigurationError(
+            "Leakage input exceeds max_records.",
+            code="LEAKAGE_RECORD_LIMIT",
+            context={"record_count": total, "max_records": resolved.max_records},
+        )
+    pair_total = sum(
+        len(left) * len(right)
+        for position, (_, left) in enumerate(items)
+        for _, right in items[position + 1 :]
+    )
+    if pair_total > resolved.max_cross_pairs:
+        raise ConfigurationError(
+            "Leakage cross-pair workload exceeds max_cross_pairs.",
+            code="LEAKAGE_PAIR_LIMIT",
+            context={"cross_pair_count": pair_total, "max_cross_pairs": resolved.max_cross_pairs},
+        )
+    all_records = tuple(record for _, dataset in items for record in dataset)
+    validate_pairwise_sequences(all_records, operation="detect_leakage")
+    events: list[LeakageEvent] = []
+    exact_count = 0
+    high_count = 0
+    for position, (left_name, left_set) in enumerate(items):
+        for right_name, right_set in items[position + 1 :]:
+            for left_index, left in enumerate(left_set):
+                for right_index, right in enumerate(right_set):
+                    exact = left.sequence.symbols == right.sequence.symbols
+                    similarity = pair_similarity(
+                        left,
+                        right,
+                        method=resolved.method,
+                        k=resolved.k,
+                        canonical=resolved.canonical,
+                        max_alignment_cells=resolved.max_alignment_cells,
+                    )
+                    if exact or similarity >= resolved.threshold:
+                        exact_count += int(exact)
+                        high_count += int(not exact and similarity >= resolved.threshold)
+                        if len(events) >= resolved.max_events:
+                            raise ConfigurationError(
+                                "Leakage event count exceeds max_events; "
+                                "no partial report returned.",
+                                code="LEAKAGE_EVENT_LIMIT",
+                                context={"max_events": resolved.max_events},
+                            )
+                        events.append(
+                            LeakageEvent(
+                                left_name,
+                                right_name,
+                                left.id,
+                                right.id,
+                                left_index,
+                                right_index,
+                                similarity,
+                                exact,
+                            )
+                        )
+    strictness = (
+        "exhaustive cross-pair exact dynamic-programming comparison"
+        if resolved.method in {"identity", "edit"}
+        else "exhaustive cross-pair deterministic k-mer/fingerprint comparison; "
+        "may miss biologically similar pairs not captured by configured features"
+    )
+    return LeakageReport(
+        tuple(events),
+        resolved.method,
+        resolved.threshold,
+        strictness,
+        exact_count,
+        high_count,
+        pair_total,
+        resolved.max_records,
+        resolved.max_cross_pairs,
+        resolved.max_events,
+        False,
+        resolved.k,
+        resolved.canonical,
+        resolved.max_alignment_cells,
+    )
+
+
+def evaluate_split_quality(
+    records: DNA | DNASet,
+    assignments: Sequence[SplitAssignment],
+    *,
+    target_ratios: Mapping[str, float],
+    label_key: str | None = None,
+    group_keys: Sequence[str] = (),
+    leakage_report: LeakageReport | None = None,
+) -> SplitQualityResult:
+    """Evaluate ratio error, label total variation, group leakage, and pair leakage."""
+
+    if not isinstance(records, (DNA, DNASet)):
+        raise ConfigurationError("records must be DNA or DNASet.")
+    dataset = records.dataset if isinstance(records, DNA) else records
+    assignment_tuple = tuple(assignments)
+    if len(assignment_tuple) != len(dataset):
+        raise ConfigurationError("assignments must align one-to-one with records.")
+    by_index: dict[int, str] = {}
+    for item in assignment_tuple:
+        if not isinstance(item, SplitAssignment) or item.input_index in by_index:
+            raise ConfigurationError("assignments contain invalid or duplicate input indices.")
+        if item.input_index >= len(dataset) or dataset[item.input_index].id != item.record_id:
+            raise ConfigurationError("assignment index/ID does not align with records.")
+        by_index[item.input_index] = item.split
+    validated_ratios: dict[str, float] = {}
+    for name, value in target_ratios.items():
+        if (
+            not isinstance(name, str)
+            or not name.strip()
+            or isinstance(value, bool)
+            or not isinstance(value, (int, float))
+            or not math.isfinite(value)
+            or value <= 0.0
+        ):
+            raise ConfigurationError(
+                "target_ratios must map non-empty names to finite positive values."
+            )
+        validated_ratios[name] = float(value)
+    split_names = tuple(validated_ratios)
+    if set(item.split for item in assignment_tuple) - set(split_names):
+        raise ConfigurationError("assignments contain names absent from target_ratios.")
+    total_ratio = math.fsum(validated_ratios.values())
+    if not math.isclose(total_ratio, 1.0, rel_tol=0.0, abs_tol=1e-9):
+        raise ConfigurationError("target_ratios must sum to one.")
+    counts = {name: sum(item.split == name for item in assignment_tuple) for name in split_names}
+    total = len(dataset)
+    achieved = {name: counts[name] / total if total else 0.0 for name in split_names}
+    deviations = {name: abs(achieved[name] - validated_ratios[name]) for name in split_names}
+    label_tv: dict[str, float] = {name: 0.0 for name in split_names}
+    if label_key is not None and total:
+        global_counts: dict[object, int] = {}
+        split_counts: dict[str, dict[object, int]] = {name: {} for name in split_names}
+        for index, record in enumerate(dataset):
+            if label_key not in record.metadata:
+                raise ConfigurationError("A record is missing label metadata.")
+            key = metadata_value_key(record.metadata[label_key])
+            global_counts[key] = global_counts.get(key, 0) + 1
+            name = by_index[index]
+            split_counts[name][key] = split_counts[name].get(key, 0) + 1
+        for name in split_names:
+            denominator = counts[name]
+            if denominator:
+                label_tv[name] = 0.5 * math.fsum(
+                    abs(split_counts[name].get(key, 0) / denominator - value / total)
+                    for key, value in global_counts.items()
+                )
+    validated_group_keys = tuple(group_keys)
+    if any(not isinstance(key, str) or not key.strip() for key in validated_group_keys):
+        raise ConfigurationError("group_keys must contain non-empty strings.")
+    if len(validated_group_keys) != len(set(validated_group_keys)):
+        raise ConfigurationError("group_keys must be unique.")
+    if label_key is not None and (not isinstance(label_key, str) or not label_key.strip()):
+        raise ConfigurationError("label_key must be non-empty or None.")
+    if leakage_report is not None and not isinstance(leakage_report, LeakageReport):
+        raise ConfigurationError("leakage_report must be LeakageReport or None.")
+    group_leaks = 0
+    for key in validated_group_keys:
+        seen: dict[object, set[str]] = {}
+        for index, record in enumerate(dataset):
+            if key not in record.metadata:
+                raise ConfigurationError("A record is missing group metadata.")
+            group_value = metadata_value_key(record.metadata[key])
+            seen.setdefault(group_value, set()).add(by_index[index])
+        group_leaks += sum(len(splits) > 1 for splits in seen.values())
+    max_ratio = max(deviations.values(), default=0.0)
+    max_label = max(label_tv.values(), default=0.0)
+    leakage_count = None if leakage_report is None else len(leakage_report.events)
+    leakage_penalty = 0.0 if leakage_count is None else min(1.0, leakage_count / max(total, 1))
+    score = max(0.0, 1.0 - max_ratio - max_label - min(1.0, group_leaks) - leakage_penalty)
+    return SplitQualityResult(
+        total,
+        FrozenDict(counts),
+        FrozenDict(validated_ratios),
+        FrozenDict(achieved),
+        FrozenDict(deviations),
+        max_ratio,
+        label_key,
+        FrozenDict(label_tv),
+        validated_group_keys,
+        group_leaks,
+        leakage_count,
+        score,
+        "max(0,1-max_ratio_deviation-max_label_TV-min(1,group_leaks)-leakage_events/max(N,1))",
+        FrozenDict(
+            {
+                "empty_split_label_tv": 0.0,
+                "group_leak_definition": "one typed metadata group present in more than one split",
+            }
+        ),
+    )
+
+
+__all__ = ["detect_leakage", "evaluate_split_quality"]

dnakit/datasets/filter.py

@@ -0,0 +1,135 @@
+"""Explicit metadata-based exclusion for immutable DNA record sets."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Literal, TypeAlias, overload
+
+from dnakit.core import DNA, DNARecord, DNASet
+from dnakit.exceptions import ConfigurationError, InputFormatError
+
+MetadataExclusionField: TypeAlias = Literal["chromosome", "species"]
+MetadataValues: TypeAlias = object | Iterable[object]
+MetadataDataset: TypeAlias = DNA | DNASet
+
+_EXCLUSION_FIELDS = frozenset({"chromosome", "species"})
+
+
+def _copy_set(dataset: DNASet, records: Iterable[DNARecord]) -> DNASet:
+    return DNASet(
+        records,
+        name=dataset.name,
+        source=dataset.source,
+        version=dataset.version,
+        metadata=dataset.metadata,
+    )
+
+
+def _materialize_values(values: MetadataValues) -> tuple[object, ...]:
+    if isinstance(values, (str, bytes)) or not isinstance(values, Iterable):
+        materialized = (values,)
+    else:
+        materialized = tuple(values)
+    if not materialized:
+        raise ConfigurationError(
+            "At least one metadata value must be excluded.",
+            code="EMPTY_METADATA_EXCLUSION_VALUES",
+        )
+    return materialized
+
+
+@overload
+def exclude_by_metadata(
+    dataset: DNA,
+    field: MetadataExclusionField,
+    values: MetadataValues,
+) -> DNA: ...
+
+
+@overload
+def exclude_by_metadata(
+    dataset: DNASet,
+    field: MetadataExclusionField,
+    values: MetadataValues,
+) -> DNASet: ...
+
+
+def exclude_by_metadata(
+    dataset: MetadataDataset,
+    field: MetadataExclusionField,
+    values: MetadataValues,
+) -> DNA | DNASet:
+    """Return a copy without records whose chromosome or species matches.
+
+    Matching is exact and compares the stored JSON-compatible metadata value.
+    Every record must contain ``field``; missing fields raise before any record
+    is removed so that an incomplete dataset cannot be silently filtered.
+    """
+
+    if not isinstance(dataset, (DNA, DNASet)):
+        raise TypeError("dataset must be DNA or DNASet.")
+    source = dataset.dataset if isinstance(dataset, DNA) else dataset
+    if not isinstance(field, str) or field not in _EXCLUSION_FIELDS:
+        raise ConfigurationError(
+            "Metadata exclusion field must be 'chromosome' or 'species'.",
+            code="INVALID_METADATA_EXCLUSION_FIELD",
+            context={"field": field},
+        )
+    excluded_values = _materialize_values(values)
+    missing_ids = tuple(record.id for record in source if field not in record.metadata)
+    if missing_ids:
+        raise InputFormatError(
+            "Every DNASet record must contain the metadata field used for exclusion.",
+            code="MISSING_METADATA_FIELD_FOR_EXCLUSION",
+            context={
+                "field": field,
+                "missing_record_ids": missing_ids[:10],
+                "missing_count": len(missing_ids),
+            },
+            hint=f"Populate metadata[{field!r}] for every record before exclusion.",
+        )
+    selected = tuple(
+        (index, record)
+        for index, record in enumerate(source)
+        if not any(record.metadata[field] == value for value in excluded_values)
+    )
+    if isinstance(dataset, DNA):
+        return dataset._derive(selected)
+    return _copy_set(dataset, (record for _, record in selected))
+
+
+@overload
+def exclude_chromosomes(dataset: DNA, chromosomes: MetadataValues) -> DNA: ...
+
+
+@overload
+def exclude_chromosomes(dataset: DNASet, chromosomes: MetadataValues) -> DNASet: ...
+
+
+def exclude_chromosomes(dataset: MetadataDataset, chromosomes: MetadataValues) -> DNA | DNASet:
+    """Return a copy without records from the selected chromosome value(s)."""
+
+    return exclude_by_metadata(dataset, "chromosome", chromosomes)
+
+
+@overload
+def exclude_species(dataset: DNA, species: MetadataValues) -> DNA: ...
+
+
+@overload
+def exclude_species(dataset: DNASet, species: MetadataValues) -> DNASet: ...
+
+
+def exclude_species(dataset: MetadataDataset, species: MetadataValues) -> DNA | DNASet:
+    """Return a copy without records from the selected species value(s)."""
+
+    return exclude_by_metadata(dataset, "species", species)
+
+
+__all__ = [
+    "MetadataExclusionField",
+    "MetadataValues",
+    "exclude_by_metadata",
+    "exclude_chromosomes",
+    "exclude_species",
+]