bioseeker 2.0.0__py3-none-any.whl

bioseeker/__init__.py

@@ -0,0 +1,9 @@
+"""BioSeeker: DNA Sequence Conservation Analyzer."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("bioseeker")
+except PackageNotFoundError:
+    # package is not installed
+    __version__ = "unknown"

bioseeker/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from bioseeker.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

bioseeker/analysis/assembler.py

@@ -0,0 +1,67 @@
+"""Aggregation of conservation results over many alignment files."""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+from .conservation import ConservationResult
+
+
+def add_rates(df: pd.DataFrame) -> pd.DataFrame:
+    """Return a copy of ``df`` with ``ConservationRate = ConservationCount / ReferenceCount``.
+
+    The rate is ``NaN`` when ``ReferenceCount`` is 0 (undefined).
+    """
+    out = df.copy()
+    ref = out["ReferenceCount"].to_numpy(dtype=float)
+    cons = out["ConservationCount"].to_numpy(dtype=float)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        out["ConservationRate"] = np.where(ref > 0, cons / np.where(ref > 0, ref, 1), np.nan)
+    return out
+
+
+class ConservationAggregator:
+    """Aggregates :class:`ConservationResult` objects from multiple files.
+
+    All results must have been produced with the same genetic code, so that
+    their rows are in the same order.
+    """
+
+    def __init__(self) -> None:
+        self._codons: Optional[pd.DataFrame] = None
+        self._pairs: Optional[pd.DataFrame] = None
+        self.n_reference_codons: int = 0
+        self.n_alignments: int = 0
+
+    def add(self, result: ConservationResult) -> None:
+        """Add a single result to the running totals."""
+        if self._codons is None:
+            self._codons = result.codons.copy()
+            self._pairs = result.pairs.copy()
+        else:
+            if not (
+                self._codons["Codon"].equals(result.codons["Codon"])
+                and self._pairs["CodonPair"].equals(result.pairs["CodonPair"])
+            ):
+                raise ValueError("Cannot aggregate results computed with different genetic codes")
+            for total, new in ((self._codons, result.codons), (self._pairs, result.pairs)):
+                for col in ("ReferenceCount", "ConservationCount"):
+                    total[col] = total[col].to_numpy() + new[col].to_numpy()
+        self.n_reference_codons += result.n_reference_codons
+        self.n_alignments += 1
+
+    @property
+    def empty(self) -> bool:
+        return self._codons is None
+
+    def get_results(self) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """Return ``(codon_df, pair_df)`` with aggregated counts and conservation rates.
+
+        Returns two empty DataFrames if nothing was added.
+        """
+        if self._codons is None:
+            return pd.DataFrame(), pd.DataFrame()
+        return add_rates(self._codons), add_rates(self._pairs)

bioseeker/analysis/conservation.py

@@ -0,0 +1,217 @@
+"""Position-specific conservation of codons and codon pairs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Sequence, Tuple
+
+import numpy as np
+import pandas as pd
+
+from ..utils.genetic_code import CODON_INDEX, get_genetic_code
+
+# Lookup table: ASCII byte -> nucleotide index in TCAG order (or -1 if invalid).
+_BASE_LUT = np.full(256, -1, dtype=np.int16)
+for _i, _b in enumerate("TCAG"):
+    _BASE_LUT[ord(_b)] = _i
+    _BASE_LUT[ord(_b.lower())] = _i
+
+
+class ReferenceNotFoundError(ValueError):
+    """Raised when the requested reference sequence is not in an alignment."""
+
+
+@dataclass
+class ConservationResult:
+    """Conservation counts for one alignment (or an aggregate of several).
+
+    Attributes:
+        codons: DataFrame with columns ``codon``, ``ReferenceCount``,
+            ``ConservationCount`` (one row per sense codon).
+        pairs: DataFrame with columns ``codon_pair``, ``ReferenceCount``,
+            ``ConservationCount`` (one row per sense codon pair).
+        n_reference_codons: Number of valid sense codons in the reference
+            (used to derive pseudocounts).
+    """
+
+    codons: pd.DataFrame
+    pairs: pd.DataFrame
+    n_reference_codons: int
+
+
+def split_into_codons(sequence: str, orf: int) -> List[str]:
+    """Split a sequence into codons starting at offset ``orf``."""
+    return [sequence[i : i + 3] for i in range(orf, len(sequence) - 2, 3)]
+
+
+def split_into_bicodons(sequence: str, orf: int) -> List[str]:
+    """Split a sequence into overlapping codon pairs starting at offset ``orf``."""
+    return [sequence[i : i + 6] for i in range(orf, len(sequence) - 5, 3)]
+
+
+def resolve_reference(ids: Sequence[str], reference_id: str | None) -> int:
+    """Return the index of ``reference_id`` in ``ids`` (0 if ``reference_id`` is None).
+
+    Raises:
+        ReferenceNotFoundError: If ``reference_id`` is not present in ``ids``.
+    """
+    if reference_id is None:
+        return 0
+    try:
+        return list(ids).index(reference_id)
+    except ValueError:
+        raise ReferenceNotFoundError(
+            f"Reference '{reference_id}' not found (available: {', '.join(ids)})"
+        ) from None
+
+
+def remove_gap_only_columns(sequences: Sequence[str]) -> List[str]:
+    """Drop alignment columns in which every sequence has a gap (``-`` or ``.``).
+
+    Such columns carry no information about the sequences being compared. They
+    appear when species are removed from a larger multiple alignment (e.g. with
+    ``--species``), and if kept they would separate codons that are adjacent in
+    every remaining sequence. In a codon-aware alignment gaps come in in-frame
+    triplets, so removing them preserves the reading frame.
+    """
+    seqs = list(sequences)
+    if not seqs or not seqs[0]:
+        return seqs
+    arr = np.frombuffer("".join(seqs).encode("ascii", "replace"), dtype=np.uint8).reshape(
+        len(seqs), -1
+    )
+    keep = ~((arr == ord("-")) | (arr == ord("."))).all(axis=0)
+    if keep.all():
+        return seqs
+    return [row.tobytes().decode("ascii") for row in arr[:, keep]]
+
+
+def encode_codons(sequences: Sequence[str], orf: int) -> np.ndarray:
+    """Encode aligned sequences as a matrix of codon indices.
+
+    Returns:
+        ``int16`` array of shape ``(n_sequences, n_codons)`` where each entry is
+        the index of the codon in :data:`~bioseeker.utils.genetic_code.ALL_CODONS`
+        (0-63), or ``-1`` if the codon contains a gap or a non-ACGT character.
+    """
+    length = len(sequences[0])
+    n_codons = max((length - orf) // 3, 0)
+    raw = np.frombuffer(
+        "".join(s[orf : orf + 3 * n_codons] for s in sequences).encode("ascii", "replace"),
+        dtype=np.uint8,
+    ).reshape(len(sequences), n_codons, 3)
+    bases = _BASE_LUT[raw]
+    idx = bases[..., 0] * 16 + bases[..., 1] * 4 + bases[..., 2]
+    idx[(bases < 0).any(axis=2)] = -1
+    return idx.astype(np.int16)
+
+
+def calculate_conservation(
+    sequences: Sequence[str],
+    orf: int = 0,
+    *,
+    reference: int = 0,
+    threshold: float = 1.0,
+    genetic_code: int = 1,
+) -> ConservationResult:
+    """Calculate codon and codon pair conservation for one alignment.
+
+    Args:
+        sequences: Aligned DNA sequences (all of the same length).
+        orf: Reading frame offset (0, 1 or 2).
+        reference: Index of the reference sequence within ``sequences``.
+        threshold: Minimum fraction of sequences (reference included) that must
+            share the reference codon for it to count as conserved (0 < t <= 1).
+        genetic_code: NCBI translation table ID used to identify stop codons.
+
+    Returns:
+        A :class:`ConservationResult`.
+
+    Raises:
+        ValueError: On invalid arguments or unaligned sequences.
+    """
+    if orf not in (0, 1, 2):
+        raise ValueError("ORF must be 0, 1, or 2")
+    if not sequences:
+        raise ValueError("No sequences provided")
+    if not 0.0 < threshold <= 1.0:
+        raise ValueError("threshold must be in the interval (0, 1]")
+    if not 0 <= reference < len(sequences):
+        raise ValueError(f"reference index {reference} out of range")
+    lengths = {len(s) for s in sequences}
+    if len(lengths) != 1:
+        raise ValueError(
+            "Sequences must be aligned (same length) for conservation analysis; "
+            f"found lengths {sorted(lengths)}"
+        )
+
+    sequences = remove_gap_only_columns(sequences)
+
+    code = get_genetic_code(genetic_code)
+    sense_mask = np.zeros(64, dtype=bool)
+    sense_idx = np.array([CODON_INDEX[c] for c in code.sense_codons], dtype=np.int64)
+    sense_mask[sense_idx] = True
+
+    idx = encode_codons(sequences, orf)
+    n_seqs = idx.shape[0]
+    ref = idx[reference]
+
+    # Valid reference positions: ACGT-only and not a stop codon.
+    ref_ok = (ref >= 0) & sense_mask[np.clip(ref, 0, 63)]
+
+    # matches[s, i]: sequence s carries the reference codon at position i.
+    matches = idx == ref[np.newaxis, :]
+    # Small tolerance so that e.g. threshold=0.9 with 10/10 or 9/10 behaves as expected.
+    min_matches = threshold * n_seqs - 1e-9
+
+    codon_conserved = matches.sum(axis=0) >= min_matches
+    pair_matches = matches[:, :-1] & matches[:, 1:]
+    pair_conserved = pair_matches.sum(axis=0) >= min_matches
+    pair_ok = ref_ok[:-1] & ref_ok[1:]
+
+    codon_ref = np.bincount(ref[ref_ok], minlength=64)
+    codon_cons = np.bincount(ref[ref_ok & codon_conserved], minlength=64)
+
+    pair_index = ref[:-1].astype(np.int32) * 64 + ref[1:].astype(np.int32)
+    pair_ref = np.bincount(pair_index[pair_ok], minlength=4096)
+    pair_cons = np.bincount(pair_index[pair_ok & pair_conserved], minlength=4096)
+
+    pair_sense_idx = (sense_idx[:, None] * 64 + sense_idx[None, :]).ravel()
+
+    codons = pd.DataFrame(
+        {
+            "Codon": list(code.sense_codons),
+            "ReferenceCount": codon_ref[sense_idx].astype(np.int64),
+            "ConservationCount": codon_cons[sense_idx].astype(np.int64),
+        }
+    )
+    pairs = pd.DataFrame(
+        {
+            "CodonPair": list(code.sense_pairs),
+            "ReferenceCount": pair_ref[pair_sense_idx].astype(np.int64),
+            "ConservationCount": pair_cons[pair_sense_idx].astype(np.int64),
+        }
+    )
+    return ConservationResult(codons=codons, pairs=pairs, n_reference_codons=int(ref_ok.sum()))
+
+
+def conservation_for_records(
+    records: Sequence[Tuple[str, str]],
+    orf: int = 0,
+    *,
+    reference_id: str | None = None,
+    threshold: float = 1.0,
+    genetic_code: int = 1,
+) -> ConservationResult:
+    """Convenience wrapper over :func:`calculate_conservation` for ``(id, seq)`` records."""
+    if not records:
+        raise ValueError("No sequences provided")
+    ids = [r[0] for r in records]
+    ref = resolve_reference(ids, reference_id)
+    return calculate_conservation(
+        [r[1] for r in records],
+        orf,
+        reference=ref,
+        threshold=threshold,
+        genetic_code=genetic_code,
+    )

bioseeker/analysis/rscu_analysis.py

@@ -0,0 +1,107 @@
+"""Relative Synonymous Codon Usage (RSCU) analysis."""
+
+from __future__ import annotations
+
+import os
+from collections import Counter
+from typing import Dict, Iterable, List
+
+import pandas as pd
+
+from ..io.reader import read_fasta
+from ..utils.genetic_code import get_genetic_code, is_valid_codon
+
+
+def count_codons_for_sequence(sequence: str) -> Counter[str]:
+    """Count non-overlapping trinucleotides in a sequence.
+
+    Gaps (``-``) are removed before counting. Ambiguous codons (containing
+    characters other than ACGT) are ignored.
+    """
+    seq_clean = sequence.replace("-", "").upper()
+    counts: Counter[str] = Counter()
+    for i in range(0, len(seq_clean) - len(seq_clean) % 3, 3):
+        codon = seq_clean[i : i + 3]
+        if is_valid_codon(codon):
+            counts[codon] += 1
+    return counts
+
+
+def calculate_rscu_from_counts(
+    codon_counts: Counter[str], genetic_code: int = 1
+) -> Dict[str, float]:
+    """Calculate RSCU values from raw codon counts.
+
+    Returns:
+        Mapping from codon to RSCU value. Stop codons are excluded. If an amino
+        acid is completely absent, all its synonymous codons get RSCU 0.
+    """
+    code = get_genetic_code(genetic_code)
+    rscu_values: Dict[str, float] = {}
+
+    for aa, syn_codons in code.synonymous_codons().items():
+        total_aa_count = sum(codon_counts[c] for c in syn_codons)
+        if total_aa_count == 0:
+            for codon in syn_codons:
+                rscu_values[codon] = 0.0
+            continue
+
+        expected = total_aa_count / len(syn_codons)
+        for codon in syn_codons:
+            rscu_values[codon] = codon_counts[codon] / expected
+
+    return rscu_values
+
+
+def global_codon_counts(files: Iterable[str | "os.PathLike[str]"]) -> Dict[str, Counter[str]]:
+    """Aggregate codon counts per species across multiple alignment files.
+
+    Args:
+        files: Paths to FASTA alignment files.
+
+    Returns:
+        Mapping from species ID to a ``Counter`` of codon occurrences.
+    """
+    global_counts: Dict[str, Counter[str]] = {}
+    for f in files:
+        for record_id, seq in read_fasta(f):
+            if record_id not in global_counts:
+                global_counts[record_id] = Counter()
+            global_counts[record_id].update(count_codons_for_sequence(seq))
+    return global_counts
+
+
+def global_rscu(files: Iterable[str | "os.PathLike[str]"], genetic_code: int = 1) -> pd.DataFrame:
+    """Calculate the global RSCU per species across multiple alignment files.
+
+    Returns:
+        A DataFrame where the index is the codon (only sense codons) and the
+        columns are the species IDs.
+    """
+    counts = global_codon_counts(files)
+    code = get_genetic_code(genetic_code)
+    species_list = sorted(counts.keys())
+
+    data = {sp: calculate_rscu_from_counts(counts[sp], genetic_code) for sp in species_list}
+
+    df = pd.DataFrame(data, index=code.sense_codons)
+    df.index.name = "Codon"
+    return df
+
+
+def identify_rare_codons(
+    rscu_df: pd.DataFrame, threshold: float = 1.0, genetic_code: int = 1
+) -> List[str]:
+    """Return sense codons where RSCU < threshold for all species.
+
+    Amino acids encoded by a single codon (e.g. Met, Trp in the Standard code)
+    are excluded since their RSCU is fixed at 1.0. Stop codons are also excluded.
+    """
+    code = get_genetic_code(genetic_code)
+    # Filter out single-codon amino acids
+    syn_fams = code.synonymous_codons()
+    multi_codons = {c for fam in syn_fams.values() if len(fam) > 1 for c in fam}
+
+    df = rscu_df[rscu_df.index.isin(multi_codons)]
+    rare = df[(df < threshold).all(axis=1)].index.tolist()
+    return sorted(rare)

bioseeker/analysis/statistics.py

@@ -0,0 +1,223 @@
+"""Codon pair statistics."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Iterable, Tuple
+
+import numpy as np
+import pandas as pd
+
+from ..utils.genetic_code import get_genetic_code
+from .assembler import add_rates
+
+
+@dataclass
+class RegressionResult:
+    """Result of a least-squares fit through the origin."""
+
+    slope: float
+    r_squared: float
+    sigma: float
+    n: int
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+def _rate_column(df: pd.DataFrame) -> pd.DataFrame:
+    return df if "ConservationRate" in df.columns else add_rates(df)
+
+
+def calculate_expected_bicodon_rates(
+    codon_df: pd.DataFrame, bicodon_df: pd.DataFrame
+) -> pd.DataFrame:
+    """Return a copy of ``bicodon_df`` with ``Codon1``, ``Codon2`` and ``ExpectedRate`` columns.
+
+    ``ExpectedRate`` is the product of the conservation rates of both codons.
+    Neither input is modified.
+    """
+    codons = _rate_column(codon_df)
+    rate_map = pd.Series(
+        codons["ConservationRate"].to_numpy(dtype=float), index=codons["Codon"].to_numpy()
+    )
+
+    df = _rate_column(bicodon_df).copy()
+    pairs = df["CodonPair"].astype(str)
+    df["Codon1"] = pairs.str[:3]
+    df["Codon2"] = pairs.str[3:]
+    r1 = df["Codon1"].map(rate_map).to_numpy(dtype=float)
+    r2 = df["Codon2"].map(rate_map).to_numpy(dtype=float)
+    df["ExpectedRate"] = r1 * r2
+    return df
+
+
+def _fit_mask(df: pd.DataFrame, x: str, y: str) -> np.ndarray:
+    mask = np.isfinite(df[x].to_numpy(dtype=float)) & np.isfinite(df[y].to_numpy(dtype=float))
+    if "ReferenceCount" in df.columns:
+        mask &= df["ReferenceCount"].to_numpy() > 0
+    return mask
+
+
+def perform_regression(
+    bicodon_df: pd.DataFrame, x: str = "ExpectedRate", y: str = "ConservationRate"
+) -> RegressionResult:
+    """Least-squares fit of ``y = m * x`` (intercept fixed at zero).
+
+    Rows with ``ReferenceCount == 0`` or non-finite values are ignored.
+
+    Returns:
+        :class:`RegressionResult` with slope, uncentred R², residual standard
+        error σ and the number of points used. Values are ``NaN`` when the fit
+        is not possible (fewer than 2 points or all ``x`` equal to zero).
+    """
+    mask = _fit_mask(bicodon_df, x, y)
+    xs = bicodon_df[x].to_numpy(dtype=float)[mask]
+    ys = bicodon_df[y].to_numpy(dtype=float)[mask]
+    n = int(mask.sum())
+
+    sxx = float(np.dot(xs, xs))
+    if n < 2 or sxx == 0.0:
+        return RegressionResult(slope=float("nan"), r_squared=float("nan"), sigma=float("nan"), n=n)
+
+    slope = float(np.dot(xs, ys) / sxx)
+    ss_res = float(np.sum((ys - slope * xs) ** 2))
+    syy = float(np.dot(ys, ys))
+    r_squared = 1.0 - ss_res / syy if syy > 0 else float("nan")
+    sigma = float(np.sqrt(ss_res / (n - 1)))
+    return RegressionResult(slope=slope, r_squared=r_squared, sigma=sigma, n=n)
+
+
+def flag_outliers(
+    bicodon_df: pd.DataFrame,
+    fit: RegressionResult,
+    sigma_threshold: float = 3.0,
+    x: str = "ExpectedRate",
+    y: str = "ConservationRate",
+) -> pd.DataFrame:
+    """Return a copy with ``FittedRate``, ``Residual``, ``SigmaDistance`` and ``Outlier`` columns.
+
+    ``Outlier`` is ``"high"`` (more conserved than predicted), ``"low"`` (less
+    conserved than predicted) or ``""``. Rows excluded from the fit get NaN.
+    """
+    df = bicodon_df.copy()
+    mask = _fit_mask(df, x, y)
+    fitted = fit.slope * df[x].to_numpy(dtype=float)
+    residual = df[y].to_numpy(dtype=float) - fitted
+    fitted[~mask] = np.nan
+    residual[~mask] = np.nan
+
+    if np.isfinite(fit.sigma) and fit.sigma > 0:
+        distance = residual / fit.sigma
+    else:
+        distance = np.full(len(df), np.nan)
+
+    outlier = np.full(len(df), "", dtype=object)
+    with np.errstate(invalid="ignore"):
+        outlier[distance > sigma_threshold] = "high"
+        outlier[distance < -sigma_threshold] = "low"
+
+    df["FittedRate"] = fitted
+    df["Residual"] = residual
+    df["SigmaDistance"] = distance
+    df["Outlier"] = outlier
+    return df
+
+
+def normalized_scores(
+    bicodon_df: pd.DataFrame, codon_df: pd.DataFrame, pseudocount: float
+) -> pd.DataFrame:
+    """Return a copy with the ``NormalizedScore`` column.
+
+    ``X = (CPCR + p) / ((CCR1 + p) * (CCR2 + p))``. Pairs never observed in the
+    reference (``ReferenceCount == 0``) get ``NaN``.
+    """
+    if pseudocount < 0:
+        raise ValueError("pseudocount must be >= 0")
+    df = (
+        bicodon_df
+        if "Codon1" in bicodon_df.columns
+        else calculate_expected_bicodon_rates(codon_df, bicodon_df)
+    )
+    df = df.copy()
+    codons = _rate_column(codon_df)
+    rate_map = pd.Series(
+        codons["ConservationRate"].to_numpy(dtype=float), index=codons["Codon"].to_numpy()
+    )
+    r1 = df["Codon1"].map(rate_map).to_numpy(dtype=float)
+    r2 = df["Codon2"].map(rate_map).to_numpy(dtype=float)
+    cpcr = df["ConservationRate"].to_numpy(dtype=float)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        score = (cpcr + pseudocount) / ((r1 + pseudocount) * (r2 + pseudocount))
+    score[df["ReferenceCount"].to_numpy() == 0] = np.nan
+    score[~np.isfinite(score)] = np.nan
+    df["NormalizedScore"] = score
+    return df
+
+
+def dipeptide_z_scores(bicodon_df: pd.DataFrame, genetic_code: int = 1) -> pd.DataFrame:
+    """Return a copy with ``Dipeptide`` and ``DipeptideZ`` columns.
+
+    ``DipeptideZ`` is the z-score of ``log(NormalizedScore)`` among all codon
+    pairs encoding the same dipeptide. Families with fewer than two valid
+    members, or with zero variance, get ``NaN``.
+    """
+    code = get_genetic_code(genetic_code)
+    df = bicodon_df.copy()
+    df["Dipeptide"] = [code.dipeptide(p) for p in df["CodonPair"].astype(str)]
+    score = df["NormalizedScore"].to_numpy(dtype=float)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        log_score = np.where(score > 0, np.log(score), np.nan)
+    log_s = pd.Series(log_score, index=df.index)
+    grouped = log_s.groupby(df["Dipeptide"].to_numpy())
+    mean = grouped.transform("mean")
+    std = grouped.transform(lambda s: s.std(ddof=1))
+    with np.errstate(divide="ignore", invalid="ignore"):
+        z = (log_s - mean) / std
+    z = z.to_numpy(dtype=float, copy=True)
+    z[~np.isfinite(z)] = np.nan
+    df["DipeptideZ"] = z
+    return df
+
+
+def analyze_pairs(
+    codon_df: pd.DataFrame,
+    pair_df: pd.DataFrame,
+    n_reference_codons: int,
+    *,
+    genetic_code: int = 1,
+    sigma_threshold: float = 3.0,
+) -> Tuple[pd.DataFrame, RegressionResult]:
+    """Run the full codon-pair analysis.
+
+    Returns:
+        ``(stats_df, fit)`` where ``stats_df`` contains the expected rates,
+        regression residuals, outlier flags, normalized scores and dipeptide
+        z-scores for every codon pair.
+    """
+    df = calculate_expected_bicodon_rates(codon_df, pair_df)
+    fit = perform_regression(df)
+    df = flag_outliers(df, fit, sigma_threshold)
+    pseudocount = 1.0 / n_reference_codons if n_reference_codons > 0 else 0.0
+    df = normalized_scores(df, codon_df, pseudocount)
+    df = dipeptide_z_scores(df, genetic_code)
+    return df, fit
+
+
+def filter_inhibitory_pairs(bicodon_df: pd.DataFrame, rare_codons: Iterable[str]) -> pd.DataFrame:
+    """Return the pairs that are high outliers and made of two rare codons."""
+    rare = {c.strip().upper() for c in rare_codons}
+    pairs = bicodon_df["CodonPair"].astype(str)
+    is_rare_pair = pairs.str[:3].isin(rare) & pairs.str[3:].isin(rare)
+    is_high = bicodon_df["Outlier"].to_numpy() == "high"
+    return bicodon_df[is_rare_pair.to_numpy() & is_high].reset_index(drop=True)
+
+
+def select_pairs(bicodon_df: pd.DataFrame, pairs: Iterable[str]) -> pd.DataFrame:
+    """Return the rows of ``bicodon_df`` for the given codon pairs (e.g. a list of known ICPs).
+
+    Pairs may be written as ``CGACGA`` or ``CGA-CGA``; RNA ``U`` is converted to ``T``.
+    """
+    wanted = [p.strip().upper().replace("-", "").replace("U", "T") for p in pairs]
+    wanted = [p for p in wanted if p]
+    return bicodon_df[bicodon_df["CodonPair"].isin(wanted)].reset_index(drop=True)