evolutionary-stability-optimizer 0.1.0__py3-none-any.whl

eso/data/human-antibody-light-chain-codon-frequencies.csv

@@ -0,0 +1,62 @@
+"codon","aa","freq_within_aa"
+"AAA","K",0.5038634756949489
+"AAC","N",0.5718761146593684
+"AAG","K",0.4961365243050511
+"AAT","N",0.4281238853406316
+"ACA","T",0.13097182238346933
+"ACC","T",0.47899857499742254
+"ACG","T",0.09268272481419175
+"ACT","T",0.29734687780491637
+"AGA","R",0.1876054334663075
+"AGC","S",0.19444975284400967
+"AGG","R",0.3922372498119939
+"AGT","S",0.20454951237884456
+"ATA","I",0.03868630942512579
+"ATC","I",0.7397642158016438
+"ATG","M",1
+"ATT","I",0.22154947477323048
+"CAA","Q",0.19296824449591132
+"CAC","H",0.6570207717474473
+"CAG","Q",0.8070317555040887
+"CAT","H",0.3429792282525527
+"CCA","P",0.33448630048322064
+"CCC","P",0.24284536707540752
+"CCG","P",0.07291725166880268
+"CCT","P",0.34975108077256917
+"CGA","R",0.0842652823706148
+"CGC","R",0.09752660203720129
+"CGG","R",0.20034523246364142
+"CGT","R",0.03802019985024105
+"CTA","L",0.05924441120383728
+"CTC","L",0.3665813872174048
+"CTG","L",0.35403072244441774
+"CTT","L",0.039708080776196295
+"GAA","E",0.4260872689539162
+"GAC","D",0.45230366253507515
+"GAG","E",0.5739127310460839
+"GAT","D",0.5476963374649249
+"GCA","A",0.2191246284363758
+"GCC","A",0.5061087270479293
+"GCG","A",0.05734268094352331
+"GCT","A",0.21742396357217159
+"GGA","G",0.1959839346229272
+"GGC","G",0.32278997536379045
+"GGG","G",0.38173182752721285
+"GGT","G",0.09949426248606953
+"GTA","V",0.07877585325542301
+"GTC","V",0.4179341238484603
+"GTG","V",0.33411562644079185
+"GTT","V",0.16917439645532487
+"TAC","Y",0.39897973273328724
+"TAT","Y",0.6010202672667128
+"TCA","S",0.08820172572782266
+"TCC","S",0.20245309080811363
+"TCG","S",0.022302532086794738
+"TCT","S",0.2880433861544147
+"TGC","C",0.6363459475159284
+"TGG","W",1
+"TGT","C",0.3636540524840716
+"TTA","L",0.07132527815882145
+"TTC","F",0.7559554651014863
+"TTG","L",0.10911012019932245
+"TTT","F",0.24404453489851372

eso/detection/_overlap.py

@@ -0,0 +1,112 @@
+"""Shared non-max-suppression helper: several detectors (independently, in both
+the primary and STABLES-derived implementations) generate multiple candidate
+rows - at different phases, frames, or seed positions - that describe the same
+real hotspot rather than genuinely distinct ones. This collapses a dataframe
+of scored, ranged candidates down to one representative per group of
+mutually-overlapping candidates.
+"""
+
+import pandas as pd
+
+
+def ranges_overlap(a, b):
+    """True if ranges (start, end) overlap, using the same exclusive-end
+    convention as Python slicing (seq[start:end]) - so two ranges that merely
+    touch at a shared boundary (e.g. (0, 950) and (950, 1250)) do NOT count
+    as overlapping, since they share no actual character position. A
+    previous `<=` version treated touching-but-adjacent ranges as
+    overlapping, which silently discarded a genuinely distinct, adjacent
+    hotspot whenever it happened to sit immediately next to a higher-scoring
+    one - found via a chunk-boundary stress test for an unrelated prototype,
+    reproduced with two homopolymer runs separated by a third with no gap.
+    """
+    return a[0] < b[1] and b[0] < a[1]
+
+
+def range_contains(outer, inner):
+    """True if `inner` (start, end) is fully contained in `outer` (start, end),
+    exclusive-end throughout (matches ranges_overlap's convention).
+    """
+    return outer[0] <= inner[0] and inner[1] <= outer[1]
+
+
+def _collapse_by_predicate(df, score_col, start_col, end_col, should_drop):
+    """Shared non-max-suppression walk: process rows in descending `score_col`
+    order (ties broken by descending span, then a stable sort, so tied rows
+    process in a fixed, reproducible order - see below), dropping a row
+    exactly when `should_drop(current_range, kept_range)` is True for some
+    already-kept range, otherwise keeping it. The two public collapse
+    functions below differ only in which predicate they pass in - everything
+    else (the sort, the kept_rows/kept_ranges bookkeeping, the empty-
+    dataframe fallback) is identical between them, so it lives here once.
+
+    The span tiebreak was added after property-based testing
+    (tests/test_detection_overlap_properties.py) found that two same-scored
+    candidates, one fully containing the other, could both survive or either
+    one survive depending purely on which happened to appear first in `df` -
+    score-only sorting doesn't order tied rows at all, so it fell back to
+    whatever incidental order the input arrived in, making the result
+    non-deterministic across runs/pandas versions for that (rare but real)
+    case. Processing the larger span first among ties makes the outcome
+    reproducible, and additionally means a fully-redundant smaller duplicate
+    gets dropped rather than kept alongside it - but this only resolves EXACT
+    ties: a smaller, genuinely higher-scoring row and a larger, lower-scoring
+    one that doesn't fully cover it can both legitimately survive regardless
+    of this tiebreak (each may represent a structurally different candidate
+    that just happens to share coordinates) - that's correct, not a bug.
+    """
+    kept_rows = []
+    kept_ranges = []
+
+    ordering = df.assign(_span=df[end_col] - df[start_col]).sort_values(
+        [score_col, '_span'], ascending=[False, False], kind='mergesort')
+
+    for _, row in ordering.iterrows():
+        current_range = (row[start_col], row[end_col])
+        if any(should_drop(current_range, kept_range) for kept_range in kept_ranges):
+            continue
+        kept_rows.append(row.drop('_span'))
+        kept_ranges.append(current_range)
+
+    return pd.DataFrame(kept_rows, columns=df.columns) if kept_rows else df.iloc[0:0]
+
+
+def collapse_overlapping_intervals(df, score_col, start_col='start', end_col='end'):
+    """Walk rows in descending `score_col` order, keeping a row only if its
+    [start_col, end_col] range doesn't overlap an already-kept row's range.
+
+    This is non-max suppression: it only requires ranges to *overlap*, not
+    that one *contain* the other, to drop the lower-scoring one. For a
+    "distinct sites" report or count that's the right call - but it means a
+    row can be dropped even though part of its range isn't actually covered
+    by anything kept, silently losing coverage of that part entirely. Do NOT
+    use this to build correction constraints for that reason - use
+    collapse_overlapping_intervals_no_coverage_loss instead. See
+    docs/detector-comparisons.md for the concrete failure this caused.
+    """
+    return _collapse_by_predicate(df, score_col, start_col, end_col, should_drop=ranges_overlap)
+
+
+def collapse_overlapping_intervals_no_coverage_loss(df, score_col, start_col='start', end_col='end'):
+    """Like collapse_overlapping_intervals, but only drops a row when its
+    range is FULLY CONTAINED in an already-kept row's range - not merely
+    overlapping it.
+
+    Walking in descending `score_col` order, a redundant candidate (one whose
+    entire range is already covered by a higher-scoring kept row - the common
+    case: several detections of the same physical site converging on
+    essentially the same extent) is still dropped, exactly as before. But a
+    candidate that only *partially* overlaps a kept row - some real,
+    independently-detected hotspot whose span isn't a subset of the kept
+    row's - is kept too, so nothing downstream ever has to build a correction
+    constraint for a region no surviving row actually covers.
+
+    Rows returned by this function can legitimately still overlap each other
+    (that's the point) - use it to feed a correction/constraint-building step,
+    never for a "how many distinct sites" count or report (use
+    collapse_overlapping_intervals for that instead).
+    """
+    def _kept_fully_covers_current(current_range, kept_range):
+        return range_contains(outer=kept_range, inner=current_range)
+
+    return _collapse_by_predicate(df, score_col, start_col, end_col, should_drop=_kept_fully_covers_current)

eso/detection/common_motifs.py

@@ -0,0 +1,81 @@
+"""A small, ready-to-use library of commonly-referenced DNA motifs worth
+checking for/avoiding when designing an engineered sequence - not just
+methylation, but a few other properties that turn up across the synthetic
+biology literature.
+
+**Methylation** (E. coli's two systems, since E. coli is already a
+first-class host here - see eso.codon_usage's bundled "e_coli" support):
+- `dam`: GATC, N6-methyladenine (essentially universal across E. coli
+  strains and many other Gammaproteobacteria).
+- `dcm`: CCWGG (W = A or T), C5-methylcytosine on the internal C.
+Sources: NEB, "Dam and Dcm Methylases of E. coli"; EcoSal Plus, "DNA
+Methylation" (doi.org/10.1128/ecosalplus.esp-0003-2013).
+
+**Cryptic ribosome binding**:
+- `shine_dalgarno`: AGGAGG, the canonical bacterial ribosome-binding-site
+  consensus. A copy of this sequence occurring *inside* a coding region
+  (not at an intended start codon) is a known source of unintended internal
+  translation initiation.
+Source: Shine-Dalgarno sequences are measurably depleted from within
+bacterial coding sequences, consistent with selection against this exact
+risk (see e.g. Mol. Biol. Evol. 35(10):2487, and PMC6107199).
+
+**Cryptic bacterial (sigma70) promoter elements**:
+- `sigma70_minus35`: TTGACA, the -35 hexamer consensus.
+- `sigma70_minus10`: TATAAT, the -10 ("Pribnow box") hexamer consensus.
+These are the two core hexamers recognized by E. coli's housekeeping sigma
+factor; an accidental occurrence of either inside a coding sequence is a
+textbook source of unwanted "cryptic" transcription. **Caveat**: a real
+sigma70 promoter needs BOTH hexamers at roughly the right spacing
+(~17±1bp apart) - this module flags each hexamer independently (this
+detector has no concept of "two motifs at a specific spacing"), so an
+isolated hit is much weaker evidence than a "both boxes, correctly spaced"
+finding would be. Treat isolated hits as a coarse, conservative screen, not
+a confirmed cryptic promoter.
+
+**Not included, and why**: transcription terminators (rho-independent
+terminators are a hairpin + poly-U structure - a secondary-structure
+property, not a fixed linear sequence motif this PSSM-based approach can
+represent) and the eukaryotic Kozak sequence (a *desired* translation-
+initiation context to match near a real start codon, not something to
+avoid - a different problem from what this detector/module is for).
+Restriction enzyme sites are also not duplicated here - DNAChisel (already
+a dependency of this project) already bundles a comprehensive registry via
+`dnachisel.list_common_enzymes()` / `dnachisel.EnzymeSitePattern`, usable
+directly with `AvoidPattern` during optimization.
+
+For anything beyond what's bundled here, REBASE (rebase.neb.com) is the
+standard reference database for restriction/methylation motifs across
+organisms - use `eso.detection.motif_utils.motif_from_consensus` to turn
+any REBASE-style (or other literature) consensus sequence into a usable
+motif, the same way everything in this module is built.
+"""
+
+from eso.detection.motif_utils import motif_from_consensus
+
+#: name -> IUPAC consensus sequence
+COMMON_MOTIFS = {
+    "dam": "GATC",
+    "dcm": "CCWGG",
+    "shine_dalgarno": "AGGAGG",
+    "sigma70_minus35": "TTGACA",
+    "sigma70_minus10": "TATAAT",
+}
+
+
+def load_common_motifs(names=None):
+    """Return a list of Bio.motifs Motif objects for the requested common
+    motifs (default: all of them - see COMMON_MOTIFS for the full list).
+
+    `names` is case-insensitive; see COMMON_MOTIFS for the available keys.
+    """
+    if names is None:
+        names = list(COMMON_MOTIFS)
+
+    motifs_list = []
+    for name in names:
+        key = name.strip().lower()
+        if key not in COMMON_MOTIFS:
+            raise ValueError(f"Unknown common motif {name!r}; choose from {sorted(COMMON_MOTIFS)}")
+        motifs_list.append(motif_from_consensus(key, COMMON_MOTIFS[key]))
+    return motifs_list

eso/detection/dispatch.py

@@ -0,0 +1,185 @@
+"""Mode-based routing across independently-developed detector implementations,
+so callers choose a tradeoff without needing to know which module originally
+implemented which algorithm.
+
+Covers recombination and slippage detection; methylation has only one
+implementation (eso.detection.methylation) - a second was built and compared
+here, but removed after it was found to disagree in accuracy (not just
+speed) with the first - see docs/detector-comparisons.md.
+"""
+
+import numpy as np
+
+from eso.detection import recombination, slippage, staubility_variant
+
+# Each category (recombination/slippage) is dispatched at three stages -
+# find the raw candidates, collapse them to a report view, and reduce them
+# to a constraint-building view (see eso.detection.recombination's module
+# docstring split for what each stage means) - across the same two
+# implementations ("thorough"/"fast" or "default"/"fast"). That's 6 mode
+# tables in total; `_dispatch` below is the one place that turns a mode
+# table + a chosen mode into either a result or a friendly ValueError, so a
+# bug fix or message tweak to that logic only has to happen once.
+
+RECOMBINATION_MODES = {
+    "thorough": recombination.find_recombination_sites,
+    "fast": staubility_variant.find_recombination_sites,
+}
+RECOMBINATION_CANDIDATE_MODES = {
+    "thorough": recombination.find_recombination_candidates,
+    "fast": staubility_variant.find_recombination_candidates,
+}
+RECOMBINATION_COLLAPSE_MODES = {
+    "thorough": recombination.collapse_recombination_sites,
+    "fast": staubility_variant.collapse_recombination_sites,
+}
+RECOMBINATION_FOR_CONSTRAINTS_MODES = {
+    "thorough": recombination.recombination_sites_for_constraints,
+    "fast": staubility_variant.recombination_sites_for_constraints,
+}
+
+SLIPPAGE_MODES = {
+    "default": slippage.find_slippage_sites,
+    "fast": staubility_variant.find_slippage_sites,
+}
+SLIPPAGE_CANDIDATE_MODES = {
+    "default": slippage.find_slippage_candidates,
+    "fast": staubility_variant.find_slippage_candidates,
+}
+SLIPPAGE_COLLAPSE_MODES = {
+    "default": slippage.collapse_slippage_sites,
+    "fast": staubility_variant.collapse_slippage_sites,
+}
+SLIPPAGE_FOR_CONSTRAINTS_MODES = {
+    "default": slippage.slippage_sites_for_constraints,
+    "fast": staubility_variant.slippage_sites_for_constraints,
+}
+
+
+def _dispatch(modes, mode, category_label, *args):
+    """Look up `mode` in `modes` and call it with `args`, or raise a
+    ValueError naming `category_label` ("recombination"/"slippage") and
+    listing the modes actually available - the one error-message format
+    every public function below shares.
+    """
+    try:
+        implementation = modes[mode]
+    except KeyError:
+        raise ValueError(f"Unknown {category_label} mode {mode!r}; choose from {sorted(modes)}")
+    return implementation(*args)
+
+
+def find_recombination_sites(seq, num_sites=np.inf, mode="thorough"):
+    """Detect recombination (RMD) hotspots, routed to one of two independently
+    developed implementations.
+
+    mode="thorough" (default) - eso.detection.recombination: Levenshtein-tolerant,
+        catches pairs of sites within edit distance 1 of each other, not just
+        exact duplicates. Benchmarked as roughly linear from 51,400nt through
+        1,000,000nt (~126.7s at 1,000,000nt, in local benchmarks after fixing
+        a pandas-overhead bottleneck - see docs/detector-comparisons.md), with
+        no breakdown point found at any tested scale - recommended by default
+        at essentially any realistic sequence length.
+
+    mode="fast" - eso.detection.staubility_variant: exact 16-mer match only,
+        via vectorized n-gram counting. Will miss a near-duplicate whenever
+        its point of divergence sits centrally enough that no 16-consecutive-nt
+        exact window survives on either side (verified: catches a duplicate
+        with a 1nt substitution near either edge, since 16+nt of exact match
+        remains; misses the same case when the substitution is centered).
+        19-34x faster than "thorough" at every length tested - reach for this
+        only when that speed gap itself matters (e.g. many-sequence batch
+        workloads), not because "thorough" becomes intractable.
+    """
+    return _dispatch(RECOMBINATION_MODES, mode, "recombination", seq, num_sites)
+
+
+def find_slippage_sites(seq, num_sites=np.inf, mode="default"):
+    """Detect slippage (SSR) hotspots, routed to one of two independently
+    developed implementations.
+
+    Unlike recombination, both modes detect exactly the same hotspots -
+    verified via 300 randomized trials with zero sensitivity or row-count
+    mismatches after fixing bugs in both implementations (see
+    docs/detector-comparisons.md). This is purely a speed choice, and
+    "default" wins it outright:
+
+    mode="default" - eso.detection.slippage: after fixing an O(n^2) candidate-
+        scan (see docs/detector-comparisons.md), this is faster than "fast"
+        at every length tested, from a few hundred nt through 300,000nt,
+        with the gap widening as length grows (10x faster at 300kb).
+
+    mode="fast" - eso.detection.staubility_variant: kept as an independent
+        second implementation (useful as a cross-check, and it's a distinct
+        algorithm, not just a slower copy) - but there is no longer a length
+        range where it's actually faster than "default".
+    """
+    return _dispatch(SLIPPAGE_MODES, mode, "slippage", seq, num_sites)
+
+
+def find_recombination_candidates(seq, mode="thorough"):
+    """Every candidate recombination (RMD) site-pair, WITHOUT collapsing
+    overlapping pairs down to one representative per real hotspot - routed to
+    one of the two implementations documented on find_recombination_sites.
+
+    This is the shared base find_recombination_sites (report view, via
+    collapse_recombination_sites) and recombination_sites_for_constraints
+    (constraint-building view) are both derived from - use whichever of
+    those two fits, not this function directly, unless you specifically want
+    every raw candidate with nothing reduced at all.
+    """
+    return _dispatch(RECOMBINATION_CANDIDATE_MODES, mode, "recombination", seq)
+
+
+def find_slippage_candidates(seq, mode="default"):
+    """Every candidate slippage (SSR) hotspot, WITHOUT collapsing overlapping
+    candidates down to one representative per physical site - routed to one
+    of the two implementations documented on find_slippage_sites.
+
+    This is the shared base find_slippage_sites (report view, via
+    collapse_slippage_sites) and slippage_sites_for_constraints
+    (constraint-building view) are both derived from - use whichever of
+    those two fits, not this function directly, unless you specifically want
+    every raw candidate with nothing reduced at all.
+    """
+    return _dispatch(SLIPPAGE_CANDIDATE_MODES, mode, "slippage", seq)
+
+
+def collapse_recombination_sites(df_pairs, num_sites=np.inf, mode="thorough"):
+    """Collapse a raw recombination-candidates dataframe (from
+    find_recombination_candidates, same `mode`) down to the human-facing
+    "distinct sites" view - one representative pair per real hotspot, limited
+    to `num_sites`. Lets a caller run detection once and derive both the raw
+    (constraint-building) and collapsed (report) views without re-detecting.
+    """
+    return _dispatch(RECOMBINATION_COLLAPSE_MODES, mode, "recombination", df_pairs, num_sites)
+
+
+def collapse_slippage_sites(df_slippage, num_sites=np.inf, mode="default"):
+    """Collapse a raw slippage-candidates dataframe (from
+    find_slippage_candidates, same `mode`) down to the human-facing "distinct
+    sites" view - one representative per physical site, limited to
+    `num_sites`. Lets a caller run detection once and derive both the raw
+    (constraint-building) and collapsed (report) views without re-detecting.
+    """
+    return _dispatch(SLIPPAGE_COLLAPSE_MODES, mode, "slippage", df_slippage, num_sites)
+
+
+def recombination_sites_for_constraints(df_pairs, mode="thorough"):
+    """Reduce a raw recombination-candidates dataframe (from
+    find_recombination_candidates, same `mode`) for feeding into
+    eso.constraints.recombination_to_multiple_avoidance_sites, WITHOUT the
+    coverage-loss risk collapse_recombination_sites has - see
+    eso.detection.recombination.recombination_sites_for_constraints.
+    """
+    return _dispatch(RECOMBINATION_FOR_CONSTRAINTS_MODES, mode, "recombination", df_pairs)
+
+
+def slippage_sites_for_constraints(df_slippage, mode="default"):
+    """Reduce a raw slippage-candidates dataframe (from
+    find_slippage_candidates, same `mode`) for feeding into
+    eso.detection.slippage.modify_df_slippage, WITHOUT the coverage-loss risk
+    collapse_slippage_sites has - see
+    eso.detection.slippage.slippage_sites_for_constraints.
+    """
+    return _dispatch(SLIPPAGE_FOR_CONSTRAINTS_MODES, mode, "slippage", df_slippage)

eso/detection/methylation.py

@@ -0,0 +1,96 @@
+"""Methylation motif detection via position-specific scoring matrices (PSSMs).
+
+Scores every position of the sequence (forward and reverse complement)
+against a set of methylation-enzyme recognition motifs and keeps the
+best-scoring match per position above random-chance probability.
+"""
+
+import numpy as np
+import pandas as pd
+from Bio import motifs
+
+from eso.sequence_utils import reverse_complement_seq
+
+SITE_COLUMNS = [
+    'start_index', 'end_index', 'matching_motif', 'PSSM_score',
+    'actual_site', 'actual_site_reverse_conjugate',
+]
+
+
+def load_motifs(motifs_path):
+    """Load PSSM motifs from a MEME-minimal-format file (e.g. topEnriched.*.meme.txt)."""
+    with open(motifs_path, "r", encoding="utf-8") as handle:
+        return list(motifs.parse(handle, "minimal"))
+
+
+def find_motif_sites(seq, num_sites, relevant_motifs):
+    """Find the best-scoring motif match at every position of `seq` (forward or
+    reverse complement, across all of `relevant_motifs`) that scores above
+    random-chance probability (PSSM log-odds > 0). Returns at most `num_sites`
+    rows, highest-scoring first.
+
+    Builds one score matrix (2*len(relevant_motifs) rows x len(seq) columns,
+    -inf where a motif doesn't reach that far) and reduces it with vectorized
+    numpy calls, rather than a per-position/per-motif Python loop building an
+    intermediate long-format dataframe with 2*len(relevant_motifs)*len(seq)
+    rows - profiling showed that intermediate frame (and a df.apply(axis=1) to
+    extract each site's sequence, now also replaced with plain zip()) was the
+    dominant cost for realistic multi-motif sets on long sequences.
+    """
+    seq_len = len(seq)
+    if not relevant_motifs or seq_len == 0:
+        return pd.DataFrame(columns=SITE_COLUMNS)
+
+    num_motifs = len(relevant_motifs)
+    scores_matrix = np.full((2 * num_motifs, seq_len), -np.inf)
+    motif_lengths = np.empty(num_motifs, dtype=int)
+    motif_names = []
+
+    for ii, motif in enumerate(relevant_motifs):
+        length = len(motif)
+        motif_lengths[ii] = length
+        motif_names.append(motif.name)
+        valid = seq_len - length + 1
+        if valid <= 0:
+            continue
+        scores_matrix[2 * ii, :valid] = motif.pssm.calculate(seq)
+        scores_matrix[2 * ii + 1, :valid] = motif.pssm.reverse_complement().calculate(seq)
+
+    # ties (equal score at the same position) resolve to the lowest motif_number,
+    # forward strand before backward - np.argmax returns the first max, and rows
+    # are laid out (motif0-fwd, motif0-rev, motif1-fwd, ...), matching this
+    # function's historical tie-breaking order.
+    best_row = np.argmax(scores_matrix, axis=0)
+    best_score = scores_matrix[best_row, np.arange(seq_len)]
+
+    keep_mask = best_score > 0
+    start_indices = np.nonzero(keep_mask)[0]
+    if start_indices.size == 0:
+        return pd.DataFrame(columns=SITE_COLUMNS)
+
+    winning_rows = best_row[keep_mask]
+    winning_scores = best_score[keep_mask]
+    winning_motif_numbers = winning_rows // 2
+    end_indices = start_indices + motif_lengths[winning_motif_numbers] - 1
+
+    # highest-scoring first, matching this function's historical output order
+    order = np.argsort(-winning_scores, kind='stable')
+    if num_sites < order.size:
+        order = order[:int(num_sites)]
+
+    start_indices = start_indices[order]
+    end_indices = end_indices[order]
+    winning_scores = winning_scores[order]
+    matching_motifs = [motif_names[m] for m in winning_motif_numbers[order]]
+
+    actual_sites = [seq[s:e + 1] for s, e in zip(start_indices, end_indices)]
+    actual_sites_rc = [reverse_complement_seq(site) for site in actual_sites]
+
+    return pd.DataFrame({
+        'start_index': start_indices,
+        'end_index': end_indices,
+        'matching_motif': matching_motifs,
+        'PSSM_score': winning_scores,
+        'actual_site': actual_sites,
+        'actual_site_reverse_conjugate': actual_sites_rc,
+    })

eso/detection/motif_utils.py

@@ -0,0 +1,77 @@
+"""Build Bio.motifs Motif objects from a plain IUPAC consensus string (e.g.
+"GATC", "CCWGG"), instead of requiring a full MEME-format PSSM file.
+
+This is the easy on-ramp for custom motifs: most methylation/restriction
+motifs are naturally described this way (REBASE, NEB, and the primary
+literature all give them as a consensus sequence with ambiguity codes, not as
+a position-probability matrix) - so there's no need to hand-author a MEME
+file just to check for one.
+"""
+
+from Bio import motifs
+
+#: IUPAC nucleotide ambiguity codes -> the bases each one represents.
+IUPAC_NUCLEOTIDE_CODES = {
+    'A': 'A', 'C': 'C', 'G': 'G', 'T': 'T',
+    'R': 'AG', 'Y': 'CT', 'S': 'GC', 'W': 'AT', 'K': 'GT', 'M': 'AC',
+    'B': 'CGT', 'D': 'AGT', 'H': 'ACT', 'V': 'ACG', 'N': 'ACGT',
+}
+
+
+def motif_from_consensus(name, consensus, pseudocount=1):
+    """Build a single Bio.motifs Motif from an IUPAC consensus string.
+
+    Each position scores an exact match to one of its allowed bases highest;
+    ambiguity codes (e.g. `W` = A or T) split probability evenly between the
+    bases they represent. A small `pseudocount` (added to every base at every
+    position, allowed or not) keeps every probability nonzero, so scoring
+    never divides by zero - it does not meaningfully weaken the requirement
+    that a real match stick to the allowed bases.
+
+    Parameters
+    ----------
+    name: str
+        Name for the resulting motif (appears as `matching_motif` in
+        eso.detection.methylation.find_motif_sites' output).
+    consensus: str
+        An IUPAC nucleotide string, e.g. "GATC" (exact) or "CCWGG"
+        (W = A or T).
+    pseudocount: int or float
+        Added to every base's raw count at every position before
+        normalizing. Higher values make the motif more tolerant of
+        near-matches; the default (1, against an allowed-base count of 100)
+        is close to an exact-match requirement.
+
+    Returns
+    -------
+    A Bio.motifs Motif, usable anywhere a MEME-file-loaded motif is (e.g.
+    eso.detection.methylation.find_motif_sites' `relevant_motifs`).
+    """
+    consensus = consensus.strip().upper()
+    if not consensus:
+        raise ValueError("consensus can't be empty.")
+
+    counts = {letter: [] for letter in 'ACGT'}
+    for position, char in enumerate(consensus):
+        allowed = IUPAC_NUCLEOTIDE_CODES.get(char)
+        if allowed is None:
+            raise ValueError(
+                f"'{char}' at position {position + 1} of '{consensus}' isn't a recognized "
+                f"IUPAC nucleotide code. Valid codes: A, C, G, T, or an ambiguity code "
+                f"({', '.join(sorted(c for c in IUPAC_NUCLEOTIDE_CODES if len(IUPAC_NUCLEOTIDE_CODES[c]) > 1))})."
+            )
+        for letter in 'ACGT':
+            counts[letter].append((100 if letter in allowed else 0) + pseudocount)
+
+    motif = motifs.Motif(counts=counts)
+    motif.name = name
+    return motif
+
+
+def motifs_from_consensus_dict(consensus_by_name, pseudocount=1):
+    """Build a list of Motifs from a plain {name: consensus_string} dict -
+    e.g. `motifs_from_consensus_dict({"my_site": "GANTC"})`. This, plus
+    `motif_from_consensus`, is all that's needed to define custom motifs
+    without a MEME file.
+    """
+    return [motif_from_consensus(name, consensus, pseudocount=pseudocount) for name, consensus in consensus_by_name.items()]