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

eso/detection/recombination.py

@@ -0,0 +1,329 @@
+"""Repeat-mediated deletion (RMD) / recombination hotspot detection.
+
+Finds pairs of near-identical sites (length >= 16, Levenshtein distance <= 1,
+non-overlapping) that are candidates for recombination-mediated deletion, and
+scores them with the empirical mutation-rate formula from the EFM Calculator
+paper (Jack et al. 2015, ACS Synthetic Biology, DOI: 10.1021/acssynbio.5b00068).
+"""
+
+import numpy as np
+import pandas as pd
+from Levenshtein import distance as levenshtein_distance
+
+from eso.detection._overlap import ranges_overlap, range_contains
+from eso.sequence_utils import add_backward_sites, shorten_sequences
+
+# matches the columns actually produced by the non-empty path below
+# (sequence_1/sequence_2, not a single 'sequence' column)
+RECOMBINATION_COLUMNS = [
+    'sequence_1', 'start_1', 'end_1', 'sequence_2', 'start_2', 'end_2',
+    'location_delta', 'site_length', 'log10_prob_recombination_ecoli',
+]
+
+
+def _generate_all_recombination_sites(seq):
+    """Generate candidate 16-17mers (forward + reverse complement) at every offset,
+    plus their single-insertion/deletion/substitution-shortened variants, so that
+    near-duplicate site pairs can be found by exact match instead of all-pairs comparison.
+    """
+    forward_insertions = [(seq[ii:ii + 17], ii, ii + 16) for ii in range(len(seq))]
+    forward_insertions = [x for x in forward_insertions if len(x[0]) == 17]
+
+    df_forward_insertions = pd.DataFrame.from_records(
+        data=forward_insertions, columns=['sequence', 'start', 'end'])
+
+    df_insertions = add_backward_sites(df_forward_insertions)
+    df_first_sites = shorten_sequences(df_forward_insertions)
+    df_substitutions = add_backward_sites(df_first_sites)
+
+    df_deletions = shorten_sequences(df_first_sites)
+    df_deletions = add_backward_sites(df_deletions)
+
+    return df_first_sites, df_insertions, df_substitutions, df_deletions
+
+
+def _generate_neighbors(curr_seq):
+    """All sequences up to one insertion, deletion, or substitution away from curr_seq."""
+    neighbors_substitutions = set()
+    neighbors_deletions = set()
+    neighbors_insertions = set()
+
+    for ii in range(len(curr_seq)):
+        prefix = curr_seq[:ii]
+        suffix = curr_seq[ii:]
+        for nt in ['A', 'C', 'G', 'T']:
+            neighbors_insertions.add(prefix + nt + suffix)
+        suffix = suffix[1:]
+        for nt in ['A', 'C', 'G', 'T']:
+            neighbors_substitutions.add(prefix + nt + suffix)
+        neighbors_deletions.add(prefix + suffix)
+
+    return neighbors_substitutions, neighbors_deletions, neighbors_insertions
+
+
+def _order_site12(df):
+    lower_second = (df.start_1 > df.start_2)
+    df_output = df.copy()
+    for col in ['sequence', 'start', 'end']:
+        df_output.loc[lower_second, f'{col}_1'] = df[f'{col}_2']
+        df_output.loc[lower_second, f'{col}_2'] = df[f'{col}_1']
+    return df_output
+
+
+def _build_sequence_index(df):
+    """Map sequence -> list of (start, end) tuples, for O(1) dict lookup instead
+    of a `df.sequence.isin(...)` filter (which rescans/reindexes the whole
+    frame) called once per candidate site.
+    """
+    index = {}
+    for sequence, start, end in zip(df.sequence, df.start, df.end):
+        index.setdefault(sequence, []).append((start, end))
+    return index
+
+
+def _generate_relevant_pairs(df_first_sites, df_insertions, df_substitutions, df_deletions):
+    """Profiling showed this function dominates find_recombination_sites'
+    runtime (5.1s of 7.0s on an ~830nt sequence), almost entirely in pandas
+    overhead: `.isin()` plus the surrounding boolean-mask filtering and
+    `.iloc`/`.loc` indexing, called once per candidate site (potentially
+    O(n) sites). Building a plain-dict index once up front, and iterating
+    the input frames as plain Python tuples via zip() rather than
+    `.iloc[ii, col]`, avoids nearly all of that per-call pandas overhead
+    while producing identical pairs.
+    """
+    pairs = []
+
+    substitutions_index = _build_sequence_index(df_substitutions)
+    deletions_index = _build_sequence_index(df_deletions)
+    insertions_index = _build_sequence_index(df_insertions)
+
+    for sequence_1, start_1, end_1 in zip(df_first_sites.sequence, df_first_sites.start, df_first_sites.end):
+        neighbors_substitutions, neighbors_deletions, neighbors_insertions = _generate_neighbors(sequence_1)
+
+        for neighbors, index in (
+            (neighbors_substitutions, substitutions_index),
+            (neighbors_deletions, deletions_index),
+            (neighbors_insertions, insertions_index),
+        ):
+            for neighbor_seq in neighbors:
+                for start_2, end_2 in index.get(neighbor_seq, ()):
+                    pairs.append((sequence_1, start_1, end_1, neighbor_seq, start_2, end_2))
+
+    df_pairs = pd.DataFrame.from_records(
+        pairs, columns=['sequence_1', 'start_1', 'end_1', 'sequence_2', 'start_2', 'end_2'])
+
+    df_pairs = _order_site12(df_pairs)
+
+    # drop overlapping pairs and duplicates
+    df_pairs = df_pairs[df_pairs.end_1 < df_pairs.start_2].drop_duplicates().reset_index(drop=True)
+
+    return df_pairs
+
+
+def _elongate_sites(row, full_seq):
+    """Extend each site pair outward while they remain within Levenshtein distance 1
+    and non-overlapping, so the reported site is the full recombination hotspot
+    rather than just its detected 16-mer core.
+    """
+    sequence_1, start_1, end_1 = row.sequence_1, row.start_1, row.end_1 + 1
+    sequence_2, start_2, end_2 = row.sequence_2, row.start_2, row.end_2 + 1
+
+    while (levenshtein_distance(full_seq[start_1:end_1 + 1], full_seq[start_2:end_2 + 1], score_cutoff=1) < 2) \
+            and (end_1 + 1 < start_2):
+        end_1 += 1
+        end_2 += 1
+
+    while (levenshtein_distance(full_seq[start_1 - 1:end_1], full_seq[start_2 - 1:end_2], score_cutoff=1) < 2) \
+            and (end_1 + 1 < start_2):
+        start_1 -= 1
+        start_2 -= 1
+
+    row.sequence_1, row.start_1, row.end_1 = full_seq[start_1:end_1], start_1, end_1
+    row.sequence_2, row.start_2, row.end_2 = full_seq[start_2:end_2], start_2, end_2
+    return row
+
+
+def calc_recombination_score(location_delta, site_length):
+    """Empirical log10 probability of recombination-mediated deletion.
+
+    Formula and constants per Oliveira et al. 2008 (Plasmid 60:159-165,
+    doi:10.1016/j.plasmid.2008.06.004), Eq. (4) and Table 3, recA+ row:
+    FR(LR,LS) = (A+LS)^(-a/LR) * LR/(1+B*LR+C*LS), with A=5.8, B=1465.6,
+    C=0 (not fitted for recA+), a=29.0 (this module's `alpha`).
+
+    The EFM Calculator's own source (github.com/barricklab/efm-calculator,
+    get_recombo_rate) hardcodes this same B=1465.6 and exponent=29, but pairs
+    them with A=8.8 - a value that does not appear anywhere in the recA+ row
+    of Table 3. It matches the *recA-* row's exponent (a=8.8 there, a
+    different parameter, in a different model, with a different B and an
+    extra C term) instead. That looks like a transcription mix-up in the
+    reference tool between the two rows of the source table, not a
+    correction - so this codebase's original 5.8 (from ESO_curr/STABLES) is
+    the value actually supported by the primary source, and the previous
+    change to 8.8 here was a mistake, reverted.
+    """
+    a, b, c, alpha = 5.8, 1465.6, 0, 29
+
+    first_component = a + location_delta
+    second_component = -1 * (alpha / site_length)
+    third_component = site_length / (1 + b * site_length + c * location_delta)
+
+    recombination_probability = (first_component ** second_component) * third_component
+    return np.log10(recombination_probability)
+
+
+def _collapse_pairs_by_predicate(df_pairs, should_drop_range):
+    """Shared non-max-suppression walk for site-pairs: process pairs in
+    descending score order (ties broken by descending combined span, then a
+    stable sort, for the same determinism reason documented on
+    eso.detection._overlap._collapse_by_predicate - found via property-based
+    testing on that same-shaped single-range logic, not reproduced here as
+    its own test but the same tiebreak applied preemptively since the walk
+    is structurally identical), dropping a pair exactly when
+    `should_drop_range` is True of BOTH its site_1 and site_2 ranges against
+    some already-kept pair's corresponding ranges, otherwise keeping it.
+    Requiring agreement on both sides (not just one) avoids merging two
+    genuinely distinct hotspots that happen to share one site. The two
+    functions below differ only in which predicate they pass in (overlap vs.
+    full containment).
+    """
+    kept_rows = []
+    kept_ranges = []  # list of ((start_1,end_1), (start_2,end_2))
+
+    combined_span = (df_pairs.end_1 - df_pairs.start_1) + (df_pairs.end_2 - df_pairs.start_2)
+    ordering = df_pairs.assign(_combined_span=combined_span).sort_values(
+        ['log10_prob_recombination_ecoli', '_combined_span'], ascending=[False, False], kind='mergesort')
+
+    for _, row in ordering.iterrows():
+        range_1 = (row.start_1, row.end_1)
+        range_2 = (row.start_2, row.end_2)
+        if any(
+            should_drop_range(range_1, r1) and should_drop_range(range_2, r2)
+            for r1, r2 in kept_ranges
+        ):
+            continue
+        kept_rows.append(row.drop('_combined_span'))
+        kept_ranges.append((range_1, range_2))
+
+    return pd.DataFrame(kept_rows, columns=df_pairs.columns) if kept_rows else df_pairs.iloc[0:0]
+
+
+def _collapse_overlapping_pairs(df_pairs):
+    """Different seed 16-mers for the same real hotspot converge, via
+    elongation, to slightly different (start, end) extents rather than one
+    canonical pair - so even exact-coordinate dedup leaves several
+    near-identical rows per real site. Collapse them via non-max suppression:
+    walk pairs in descending score order, keeping a pair only if BOTH its
+    site_1 and site_2 ranges are still free of an already-kept pair's
+    corresponding range.
+    """
+    return _collapse_pairs_by_predicate(df_pairs, should_drop_range=ranges_overlap)
+
+
+def _collapse_overlapping_pairs_no_coverage_loss(df_pairs):
+    """Like _collapse_overlapping_pairs, but only drops a pair when BOTH its
+    site_1 and site_2 ranges are FULLY CONTAINED in an already-kept pair's
+    corresponding ranges - not merely overlapping them. See
+    eso.detection._overlap.collapse_overlapping_intervals_no_coverage_loss
+    for why: plain overlap-based NMS can silently drop a genuinely distinct,
+    only-partially-overlapping hotspot pair, leaving whatever part of its
+    span isn't covered by the kept pair with no correction constraint. Rows
+    returned here can legitimately still overlap each other - use this to
+    build constraints, never for a "how many distinct sites" count (use
+    _collapse_overlapping_pairs for that instead, via collapse_recombination_sites).
+    """
+    def _kept_fully_covers_current(current_range, kept_range):
+        return range_contains(outer=kept_range, inner=current_range)
+
+    return _collapse_pairs_by_predicate(df_pairs, should_drop_range=_kept_fully_covers_current)
+
+
+def recombination_sites_for_constraints(df_pairs):
+    """Reduce raw recombination candidates (see find_recombination_candidates)
+    for feeding into correction-constraint building
+    (recombination_to_multiple_avoidance_sites), WITHOUT the coverage-loss
+    risk plain non-max suppression (collapse_recombination_sites) has - see
+    _collapse_overlapping_pairs_no_coverage_loss and
+    eso.detection.slippage.slippage_sites_for_constraints for the concrete
+    failure this avoids.
+    """
+    if df_pairs.shape[0] == 0:
+        return df_pairs
+    return _collapse_overlapping_pairs_no_coverage_loss(df_pairs)
+
+
+def find_recombination_candidates(seq):
+    """Find every candidate recombination (RMD) site-pair in `seq`, WITHOUT
+    collapsing overlapping pairs down to one representative per real hotspot.
+
+    A pair of sites is a candidate if both are >=16nt, within Levenshtein
+    distance 1 of each other, and non-overlapping.
+
+    This is the shared base both find_recombination_sites (collapsed report
+    view) and recombination_sites_for_constraints (constraint-building view)
+    are built from.
+
+    Returns a dataframe sorted by descending mutation risk
+    (`log10_prob_recombination_ecoli`), not limited by `num_sites` (that only
+    makes sense for the collapsed, human-facing view - see
+    find_recombination_sites/collapse_recombination_sites).
+    """
+    empty_df = pd.DataFrame(columns=RECOMBINATION_COLUMNS)
+
+    df_first_sites, df_insertions, df_substitutions, df_deletions = _generate_all_recombination_sites(seq)
+    df_pairs = _generate_relevant_pairs(df_first_sites, df_insertions, df_substitutions, df_deletions)
+
+    if df_pairs.shape[0] == 0:
+        return empty_df
+
+    df_pairs = df_pairs.apply(lambda row: _elongate_sites(row, seq), axis=1)
+
+    df_pairs.loc[:, 'location_delta'] = df_pairs.start_2 - df_pairs.end_1
+    df_pairs.loc[:, 'site_length'] = df_pairs.apply(
+        lambda row: max(row.end_1 - row.start_1, row.end_2 - row.start_2), axis=1)
+
+    df_pairs.loc[:, 'log10_prob_recombination_ecoli'] = df_pairs.apply(
+        lambda x: calc_recombination_score(x.location_delta, x.site_length), axis=1)
+
+    df_pairs = df_pairs[df_pairs.log10_prob_recombination_ecoli > -9]
+
+    for col in ['start_1', 'end_1', 'start_2', 'end_2', 'location_delta', 'site_length']:
+        df_pairs.loc[:, col] = df_pairs[col].astype(int)
+
+    return df_pairs.sort_values('log10_prob_recombination_ecoli', ascending=False).reset_index(drop=True)
+
+
+def collapse_recombination_sites(df_pairs, num_sites=np.inf):
+    """Collapse raw recombination candidates (see find_recombination_candidates)
+    down to one representative pair per group of overlapping pairs, for a
+    human-facing "distinct sites" report or count - NOT for building
+    correction constraints (see recombination_sites_for_constraints instead -
+    a dropped pair's uniquely-covered span would otherwise get no fix).
+
+    The many candidate-seed rows that converge (via elongation) on the same
+    or overlapping real hotspot are collapsed down to one representative row
+    each.
+    """
+    if df_pairs.shape[0] == 0:
+        return df_pairs
+
+    df_pairs = _collapse_overlapping_pairs(df_pairs)
+    df_pairs = df_pairs.sort_values('log10_prob_recombination_ecoli', ascending=False)
+
+    if num_sites < np.inf:
+        df_pairs = df_pairs.head(int(num_sites))
+
+    return df_pairs
+
+
+def find_recombination_sites(seq, num_sites=np.inf):
+    """Find recombination (RMD) hotspots in `seq`, collapsed to one
+    representative pair per real hotspot (see collapse_recombination_sites)
+    and limited to `num_sites` distinct site-pairs if given - the
+    human-facing report/count view. Do NOT use this to build correction
+    constraints (see find_recombination_candidates).
+
+    Returns a dataframe sorted by descending mutation risk
+    (`log10_prob_recombination_ecoli`).
+    """
+    return collapse_recombination_sites(find_recombination_candidates(seq), num_sites)

eso/detection/slippage.py

@@ -0,0 +1,249 @@
+"""Replication-slippage (SSR - simple sequence repeat) hotspot detection.
+
+Finds short tandem repeats (base units of length 1-15 repeated 3+ times, or a
+single nucleotide repeated 12+ times) and scores them with the empirical
+mutation-rate formula from the EFM Calculator paper (Jack et al. 2015, ACS
+Synthetic Biology, DOI: 10.1021/acssynbio.5b00068).
+
+The length-1 (homopolymer) minimum is 12, not 3, for two stacked reasons:
+
+1. log10_prob = -12.9 + 0.729*n crosses the -9 filter cutoff (applied below)
+   at n=6 - runs of n=4/5 always fail it and are never worth detecting.
+2. Every homopolymer run of n>=6 is *also* always detected as a length-2 site
+   (any 6+ identical characters trivially contain "XX" repeated 3+ times),
+   scored as -4.749 + 0.063*floor(n/2) - and collapse_overlapping_intervals
+   below only keeps the single highest-scoring representation per physical
+   site. Comparing the two formulas: the length-1 score grows ~0.729/nt while
+   the length-2 score grows only ~0.0315/nt, so length-2 always wins for
+   n=6..11 (e.g. n=8: length-1 -7.068 vs length-2 -4.497) - the length-1
+   detection is real but its result is always discarded. The crossover is
+   n=12 exactly (length-1 -4.152 vs length-2 -4.371) - only from there does
+   the length-1 reading start being the one that survives, correctly
+   reflecting a homopolymer run's much higher risk than a linear-in-repeats
+   length-2 score would suggest.
+
+So detecting length-1 sites below n=12 is provably pure waste - the result
+never changes the final output regardless, since length-2 detection (run
+independently, over the same sequence) always produces a same-or-better-scoring
+overlapping candidate for that region. This doesn't apply to length>1 units:
+log10_prob = -4.749 + 0.063*n is already > -9 at the smallest detectable n=3,
+so every length>1 candidate always passes the -9 filter on its own.
+"""
+
+import numpy as np
+import pandas as pd
+
+from eso.detection._overlap import collapse_overlapping_intervals, collapse_overlapping_intervals_no_coverage_loss
+
+SLIPPAGE_COLUMNS = ['start', 'end', 'length_base_unit', 'sequence']
+
+
+def _find_all(a_str, sub):
+    """Non-overlapping occurrences of `sub` in `a_str`."""
+    start = 0
+    while True:
+        start = a_str.find(sub, start)
+        if start == -1:
+            return
+        yield start
+        start += len(sub)
+
+
+def _find_longest_match(seq, subunit, start_index):
+    """Given a start location and a repeat unit, find the full extent of the run."""
+    curr_seq = seq[start_index:]
+    len_sub = len(subunit)
+    end_shift = 0
+    while curr_seq[:len_sub] == subunit:
+        end_shift += len_sub
+        curr_seq = curr_seq[len_sub:]
+    end_index = start_index + end_shift
+    return start_index, end_index, seq[start_index:end_index], len_sub
+
+
+def _generate_slippage_sites_current_subunit(seq, subunit):
+    curr_slippage_sites = []
+    # 12 for length-1 units (below that, length-2 detection of the same
+    # region always outscores it - see module docstring), 3 for longer units.
+    subseq = subunit * (12 if len(subunit) == 1 else 3)
+
+    indexes_curr = list(_find_all(seq, subseq))
+    if not indexes_curr:
+        return curr_slippage_sites
+
+    curr_slippage_sites.append(_find_longest_match(seq, subunit, indexes_curr[0]))
+
+    for index in indexes_curr[1:]:
+        end_previous_site = curr_slippage_sites[-1][1]
+        if index <= end_previous_site:
+            continue
+        curr_slippage_sites.append(_find_longest_match(seq, subunit, index))
+
+    return curr_slippage_sites
+
+
+def _find_slippage_len1(seq):
+    slippage_sites = []
+    for nt in ['A', 'C', 'G', 'T']:
+        slippage_sites.extend(_generate_slippage_sites_current_subunit(seq, nt))
+    return pd.DataFrame.from_records(
+        data=slippage_sites, columns=['start', 'end', 'sequence', 'length_base_unit'],
+    ).drop_duplicates().reset_index(drop=True)
+
+
+def _find_relevant_subunits_len_l(seq, length):
+    """Unique substrings of `length` that appear 3+ times in a row, as repeat-unit candidates.
+
+    Profiling showed the original approach - build every unique substring,
+    then call `seq.find(subunit*3)` once per candidate - spends ~93% of total
+    find_slippage_sites runtime in `str.find` (88,151 calls on a 9.6kb random
+    sequence), since each call rescans the whole sequence: O(unique
+    candidates) x O(n) = O(n^2) for a sequence with mostly-unique substrings.
+    Building a position dict in one pass and checking adjacency via O(1) set
+    membership (positions p, p+length, p+2*length all present means
+    `subunit*3` occurs at p) is equivalent but O(n) instead.
+    """
+    positions_by_subunit = {}
+    for ii in range(len(seq) - length + 1):
+        positions_by_subunit.setdefault(seq[ii:ii + length], []).append(ii)
+
+    relevant = []
+    for subunit, positions in positions_by_subunit.items():
+        position_set = set(positions)
+        if any((p + length) in position_set and (p + 2 * length) in position_set for p in positions):
+            relevant.append(subunit)
+
+    return sorted(relevant)
+
+
+def _find_slippage_len_l(seq, length):
+    """Note: 1 < length < 16."""
+    relevant_subunits = _find_relevant_subunits_len_l(seq, length)
+    slippage_sites = []
+    for subunit in relevant_subunits:
+        slippage_sites.extend(_generate_slippage_sites_current_subunit(seq, subunit))
+    return pd.DataFrame.from_records(data=slippage_sites, columns=['start', 'end', 'sequence', 'length_base_unit'])
+
+
+def find_slippage_candidates(seq):
+    """Find every candidate slippage (SSR) hotspot in `seq` across repeat-unit
+    lengths 1-15, WITHOUT collapsing overlapping candidates down to one
+    representative per physical site.
+
+    This is the shared base both find_slippage_sites (collapsed report view,
+    via collapse_slippage_sites) and slippage_sites_for_constraints
+    (constraint-building view) are built from - see the latter for why
+    building constraints needs something other than plain non-max
+    suppression.
+
+    Returns a dataframe sorted by descending mutation risk
+    (`log10_prob_slippage_ecoli`), not limited by `num_sites` (that only
+    makes sense for the collapsed, human-facing view - see
+    find_slippage_sites/collapse_slippage_sites).
+    """
+    slippage_sites_list = [_find_slippage_len1(seq)]
+    for length in range(2, 16):
+        slippage_sites_list.append(_find_slippage_len_l(seq, length))
+    df_slippage = pd.concat(slippage_sites_list, ignore_index=True)[SLIPPAGE_COLUMNS]
+
+    df_slippage.loc[:, 'num_base_units'] = (
+        df_slippage.sequence.apply(len) / df_slippage.length_base_unit
+    ).astype(int)
+
+    df_slippage.loc[:, 'log10_prob_slippage_ecoli'] = -4.749 + 0.063 * df_slippage['num_base_units']
+    df_slippage.loc[df_slippage.length_base_unit == 1, 'log10_prob_slippage_ecoli'] = (
+        -12.9 + 0.729 * df_slippage['num_base_units']
+    )
+
+    df_slippage = df_slippage[df_slippage.log10_prob_slippage_ecoli > -9]
+    return df_slippage.sort_values('log10_prob_slippage_ecoli', ascending=False).reset_index(drop=True)
+
+
+def slippage_sites_for_constraints(df_slippage):
+    """Reduce raw slippage candidates (see find_slippage_candidates) for
+    feeding into correction-constraint building (modify_df_slippage), WITHOUT
+    the coverage-loss risk plain non-max suppression (collapse_slippage_sites)
+    has.
+
+    Regular NMS (`collapse_overlapping_intervals`, used by
+    collapse_slippage_sites) only requires two candidates' ranges to
+    *overlap*, not that one *contain* the other, before dropping the
+    lower-scoring one - so two genuinely distinct, only-partially-overlapping
+    hotspots can have the lower-scoring one dropped entirely, silently
+    leaving the part of its span the higher-scoring one doesn't cover with no
+    correction constraint at all. Concrete case: a length-2 site over
+    [0, 10) and a length-3 site over [8, 20) overlap only at [8, 10) -
+    collapsing keeps whichever scores higher and drops the other completely,
+    so positions [10, 20) (if the length-2 site wins) would get no
+    constraint, even though the length-3 site was a real,
+    independently-detected hotspot. See docs/detector-comparisons.md.
+
+    This uses `collapse_overlapping_intervals_no_coverage_loss` instead: a
+    candidate is only dropped if its ENTIRE range is already covered by a
+    higher-scoring kept candidate - the common case (several detections
+    converging on essentially the same physical site) still collapses down
+    to one row as before, but a candidate sticking out beyond every
+    higher-scoring one it overlaps is kept, so every real hotspot still gets
+    a constraint covering its full extent, not just whatever a single
+    NMS survivor happened to cover.
+    """
+    return collapse_overlapping_intervals_no_coverage_loss(df_slippage, score_col='log10_prob_slippage_ecoli')
+
+
+def collapse_slippage_sites(df_slippage, num_sites=np.inf):
+    """Collapse raw slippage candidates (see find_slippage_candidates) down to
+    one representative per group of overlapping candidates, for a
+    human-facing "distinct sites" report or count - NOT for building
+    correction constraints (see slippage_sites_for_constraints instead - a
+    dropped candidate's uniquely-covered span would otherwise get no fix).
+
+    different base-unit lengths (and different phase offsets within the same
+    length) can each detect the same physical repeat as a separate row -
+    e.g. "GCGCGCGC" is a valid length-2 run starting at position N, AND its
+    1-shifted substring "CGCGCG" is a separate valid length-2 run starting
+    at N+1. Collapsing by exact 'start' alone (an earlier approach) misses
+    this, since the rows don't share a start position. Keep one
+    representative (highest scoring) per group of overlapping ranges instead.
+    """
+    df_slippage = collapse_overlapping_intervals(df_slippage, score_col='log10_prob_slippage_ecoli')
+    df_slippage = df_slippage.sort_values(['log10_prob_slippage_ecoli', 'length_base_unit'], ascending=[False, False])
+
+    if num_sites < np.inf:
+        df_slippage = df_slippage.head(int(num_sites))
+
+    return df_slippage
+
+
+def find_slippage_sites(seq, num_sites=np.inf):
+    """Find slippage (SSR) hotspots in `seq`, collapsed to one representative
+    per physical site (see collapse_slippage_sites) and limited to
+    `num_sites` if given - the human-facing report/count view. Do NOT use
+    this to build correction constraints (see slippage_sites_for_constraints).
+
+    Returns a dataframe sorted by descending mutation risk
+    (`log10_prob_slippage_ecoli`).
+    """
+    return collapse_slippage_sites(find_slippage_candidates(seq), num_sites)
+
+
+def modify_df_slippage(df_slippage):
+    """Convert each slippage-site row (N repeated base units) into ~N/2 rows of
+    individual base units to avoid (skipping every other one) - enough to
+    disrupt the repeat without necessarily eliminating it entirely.
+
+    Example: a row for "TGTGTGTGTG" (base unit "TG", num_base_units=5) becomes
+    3 rows, each a single "TG" occurrence and its coordinates.
+    """
+    df_list = []
+
+    for idx in df_slippage.index:
+        num_base_units = df_slippage.loc[idx].num_base_units
+        length = df_slippage.loc[idx].length_base_unit
+        for i in range(0, (num_base_units - 1), 2):
+            df_list.append({
+                'sequence': df_slippage.loc[idx].sequence[int(i * length):int((i + 1) * length)],
+                'start': int(df_slippage.loc[idx].start + i * length),
+                'end': int(df_slippage.loc[idx].start + (i + 1) * length),
+            })
+
+    return pd.DataFrame(df_list)