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

eso/optimize.py

@@ -0,0 +1,266 @@
+"""DNAChisel-based sequence optimization: enforce translation, GC-content
+windows, codon usage, and avoidance of detected hypermutable sites.
+"""
+
+import warnings
+
+import pandas as pd
+import dnachisel
+from dnachisel.DnaOptimizationProblem import NoSolutionError
+
+from eso.codon_usage import CODON_USAGE_TABLES
+from eso.constraints import (
+    convert_df_to_constraints,
+    exclusion_site_correcter,
+    recombination_to_multiple_avoidance_sites,
+)
+from eso.custom_score import CustomScore
+from eso.detection.slippage import modify_df_slippage
+
+# Substring DNAChisel raises when an AvoidPattern's location doesn't align to
+# the codon grid under EnforceTranslation: DnaOptimizationProblem.resolve_constraint
+# can compute a "jointly mutable" mutation-space region (accounting for codon
+# interdependencies) that ends up not overlapping the constraint's own declared
+# location at all. AvoidPattern.localized() correctly returns None for that
+# (they genuinely don't overlap) - but the DNAChisel caller doesn't check for
+# None before calling .evaluate() on it. Confirmed via direct reproduction with
+# a non-codon-aligned 2nt repeat and, separately, a 1nt homopolymer run; a
+# codon-aligned repeat (e.g. a 3nt unit) never triggers it.
+#
+# An earlier fix widened every avoid-window outward to whole codons before
+# building the AvoidPattern, which does dodge this crash - but it also changes
+# what's being asked for: "avoid this pattern at this spot" becomes "avoid this
+# pattern ANYWHERE in the whole codon", which for a single-nucleotide pattern
+# in a homopolymer run can make the constraint unsatisfiable for every codon in
+# the run (e.g. all-Phe TTT/TTC codons always contain a T), silently dropping
+# every constraint and leaving the site untouched - no crash, but no effect
+# either (confirmed directly: a "ATG"+"T"*12+"TAA" homopolymer produced
+# num_edits=0 with that approach). So instead of forcing this by widening the
+# window, the retry loop below simply catches the crash like any other
+# unsatisfiable-constraint case and drops whichever constraints are actually
+# still failing, exactly as it already did for DNAChisel's own
+# NoSolutionError-with-no-named-constraint case.
+_LOCALIZED_NONE_CRASH_MESSAGE = "'NoneType' object has no attribute 'evaluate'"
+
+
+def _warn_dropped_constraint(constraint):
+    warnings.warn(
+        f"Could not satisfy constraint {constraint} - dropping it and continuing without it. "
+        "This most often happens when disrupting a detected hypermutable site would require a "
+        "change that conflicts with another hard constraint, most commonly translation "
+        "preservation (e.g. every synonymous codon at that position still contains the pattern "
+        "being avoided, such as a homopolymer landing on a Met/Trp codon with no alternative). "
+        "The site this constraint was protecting was left unmodified in the final sequence.",
+        stacklevel=3,
+    )
+
+
+def _codon_optimization_objectives(organism_name, orf_regions, method):
+    """Build DNAChisel CodonOptimize objectives.
+
+    `organism_name` may be one of eso.codon_usage.CODON_USAGE_TABLES' custom
+    tables (not present in the Kazusa database), or any species/TaxID
+    supported by python-codon-tables.
+    """
+    if organism_name in CODON_USAGE_TABLES:
+        codon_usage_table = CODON_USAGE_TABLES[organism_name]()
+        return [
+            dnachisel.CodonOptimize(location=orf, codon_usage_table=codon_usage_table.copy(), method=method)
+            for orf in orf_regions
+        ]
+
+    try:
+        return [dnachisel.CodonOptimize(species=organism_name, location=orf, method=method) for orf in orf_regions]
+    except Exception:
+        print('unknown organism, no codon optimization!')
+        return []
+
+
+def optimization_engine(
+    seq,
+    mini_gc=0.3,
+    maxi_gc=0.7,
+    window_size_gc=50,
+    method='use_best_codon',
+    organism_name='not_specified',
+    custom_score_fn=None,
+    custom_score_minimize=False,
+    df_recombination=None,
+    df_slippage=None,
+    df_motifs=None,
+    orf_regions=(),
+    exclusion_regions=(),
+):
+    """Optimize `seq` for codon usage, GC content, and (if hotspot dataframes
+    are given) avoidance of detected recombination/slippage/methylation sites,
+    while preserving the amino-acid translation over `orf_regions`.
+
+    Citation: Jack, Leonard, Mishler, Renda, Leon, Suarez & Barrick (2015).
+    "Predicting the genetic stability of engineered DNA sequences with the
+    EFM Calculator." ACS Synthetic Biology. DOI: 10.1021/acssynbio.5b00068
+
+    Parameters
+    ----------
+    seq: str
+        DNA sequence (ACGT alphabet).
+    mini_gc, maxi_gc: float in [0, 1]
+        Allowed GC-content range within any `window_size_gc`-nt window.
+    method: {"use_best_codon", "match_codon_usage", "harmonize_rca"}
+        Codon optimization strategy (see DNAChisel's CodonOptimize).
+    organism_name: str
+        Host organism for codon optimization: one of
+        eso.codon_usage.CODON_USAGE_TABLES' keys, a python-codon-tables
+        species name/TaxID, or "not_specified" to skip codon optimization.
+    custom_score_fn: callable(str) -> float, or None
+        If given, replaces the CodonOptimize (CAI/tAI-style) objective with
+        eso.custom_score.CustomScore wrapping this function (higher is
+        better sequence, unless custom_score_minimize=True). `organism_name`
+        and `method` are then ignored. Called once per ORF, on the whole ORF,
+        for every trial mutation during optimization - can be slow on long
+        sequences or an expensive custom_score_fn (a warning is raised).
+    custom_score_minimize: bool
+        If True, treats a lower custom_score_fn value as better.
+    df_recombination, df_slippage, df_motifs: pandas.DataFrame or None
+        Detected hotspots to avoid (from eso.detection.*); pass None or an
+        empty dataframe to skip a given constraint type.
+    orf_regions: sequence of (start, end) tuples
+        Regions to keep in-frame and translation-preserving. Defaults to the
+        whole sequence, trimmed to a multiple of 3.
+    exclusion_regions: sequence of (start, end) tuples
+        Regions that must not be modified.
+
+    Returns
+    -------
+    (final_sequence, objectives_summary, num_edits)
+    """
+    if df_recombination is None:
+        df_recombination = pd.DataFrame()
+    if df_slippage is None:
+        df_slippage = pd.DataFrame()
+    if df_motifs is None:
+        df_motifs = pd.DataFrame()
+
+    if len(orf_regions) == 0:
+        new_last_index = ((len(seq) - 1) // 3) * 3
+        orf_regions = [(0, new_last_index)]
+
+    if custom_score_fn is not None:
+        # Scoped to each ORF individually, matching how _codon_optimization_objectives
+        # already scopes CodonOptimize to `location=orf` - without this, custom scoring
+        # would apply across the whole sequence including any non-ORF flanks (UTRs,
+        # locked regions), inconsistent with codon-usage scoring's own ORF-only behavior.
+        obj = [
+            CustomScore(custom_score_fn, location=orf, minimize=custom_score_minimize)
+            for orf in orf_regions
+        ]
+    else:
+        obj = _codon_optimization_objectives(organism_name, orf_regions, method)
+
+    cnst = [dnachisel.EnforceGCContent(mini=mini_gc, maxi=maxi_gc, window=window_size_gc)]
+    for orf in orf_regions:
+        cnst.append(dnachisel.EnforceTranslation(location=orf))
+
+    cnst.extend(dnachisel.AvoidChanges(location=region) for region in exclusion_regions)
+
+    if not df_recombination.empty:
+        df_rec = recombination_to_multiple_avoidance_sites(df_recombination, exclusion_regions)
+        df_rec = exclusion_site_correcter(df_rec, exclusion_regions)
+        cnst.extend(convert_df_to_constraints(df_rec))
+
+    if not df_slippage.empty:
+        df_slip = modify_df_slippage(df_slippage)
+        df_slip = exclusion_site_correcter(df_slip.copy(), exclusion_regions)
+        cnst.extend(convert_df_to_constraints(df_slip))
+
+    if not df_motifs.empty:
+        df_mot = df_motifs.copy()[['start_index', 'end_index', 'actual_site']].rename(
+            columns={'start_index': 'start', 'end_index': 'end', 'actual_site': 'sequence'})
+        df_mot.loc[:, 'start'] = df_mot['start'].astype(int)
+        # eso.detection.methylation's end_index is INCLUSIVE (the index of the
+        # motif's last nucleotide), but everything downstream of here -
+        # exclusion_site_correcter, convert_df_to_constraints, and DNAChisel's
+        # own Location - uses EXCLUSIVE end (matching Python slicing). Without
+        # the +1, every motif's AvoidPattern location was exactly one
+        # nucleotide too short to ever contain its own pattern, so
+        # DNAChisel could never find it there and always reported the
+        # constraint as trivially satisfied - methylation-motif avoidance
+        # silently did nothing. Confirmed directly: before this fix, a GATC
+        # motif passed as df_motifs survived optimization completely
+        # untouched (0 edits); see tests/test_optimize.py.
+        df_mot.loc[:, 'end'] = df_mot['end'].astype(int) + 1
+        df_mot = exclusion_site_correcter(df_mot, exclusion_regions)
+        cnst.extend(convert_df_to_constraints(df_mot))
+
+    problem = None
+    flag = 0
+    # 60 was chosen empirically back when constraint counts were always small
+    # (num_sites capped how many hotspot-avoidance constraints existed at
+    # all). Since num_sites became report-only and constraint-building
+    # started using every raw, uncollapsed candidate (see
+    # docs/detector-comparisons.md's overlap-collapse coverage-gap entry), a
+    # single dense/repetitive sequence can legitimately produce well over 60
+    # individual AvoidPattern constraints - a fixed 60-round budget could then
+    # raise NoSolutionError purely from running out of retries, not from any
+    # actual unresolvable conflict. Scale the budget with how many
+    # constraints there actually are (computed once, before any get dropped,
+    # so it doesn't shrink alongside `cnst` as rounds progress), keeping 60 as
+    # the floor for the common, small-constraint-count case this was
+    # originally tuned for.
+    retry_budget = max(60, len(cnst))
+    while flag < retry_budget:  # retry, dropping unsatisfiable/crashing constraints
+        problem = dnachisel.DnaOptimizationProblem(sequence=str(seq), constraints=cnst, objectives=obj)
+        try:
+            problem.resolve_constraints()
+            break
+        except NoSolutionError as e:
+            if e.constraint is not None:
+                _warn_dropped_constraint(e.constraint)
+                cnst.remove(e.constraint)
+                flag += 1
+                continue
+            drop_and_retry = True
+        except AttributeError as e:
+            # See _LOCALIZED_NONE_CRASH_MESSAGE above: a genuine DNAChisel-internal
+            # crash on non-codon-aligned AvoidPattern locations. Only swallow this
+            # exact crash - anything else with this type is a real bug, re-raise it.
+            if _LOCALIZED_NONE_CRASH_MESSAGE not in str(e):
+                raise
+            drop_and_retry = True
+
+        if drop_and_retry:
+            # Either DNAChisel's own final consistency check
+            # (perform_final_constraints_check, run at the end of
+            # resolve_constraints) failed without identifying a single culprit
+            # constraint - NoSolutionError.constraint defaults to None, seen in
+            # practice with several individually-resolvable but densely packed
+            # AvoidPattern constraints that regress each other by the time
+            # solving reaches the last one - or resolve_constraint itself
+            # crashed on a non-codon-aligned AvoidPattern location. Either way,
+            # `cnst.remove(None)` isn't possible here, so instead re-evaluate
+            # every constraint ourselves and drop whichever ones are still
+            # actually failing, so the retry loop can keep making progress the
+            # same way it does for the normal case. Constraints like
+            # EnforceGCContent have location=None until
+            # initialized_on_problem() fills it in (as a copy, not in-place) -
+            # evaluate that initialized copy, not the raw constraint, which
+            # would crash the same way on its own unset location.
+            failing = [
+                c for c in cnst
+                if not c.initialized_on_problem(problem, role='constraint').evaluate(problem).passes
+            ]
+            if not failing:
+                raise
+            for constraint in failing:
+                _warn_dropped_constraint(constraint)
+                cnst.remove(constraint)
+            flag += 1
+    else:
+        raise NoSolutionError(
+            f"More than {retry_budget} hard constraints were not satisfied ({flag}).", problem=problem)
+
+    problem.optimize()
+    obj_description = problem.objectives_text_summary()
+    num_edits = problem.number_of_edits()
+    final_sequence = str(problem.sequence).upper()
+
+    return final_sequence, obj_description, num_edits

eso/pipeline.py

@@ -0,0 +1,322 @@
+"""End-to-end orchestration: for each sequence file, run codon/GC optimization,
+detect hypermutable sites, re-optimize while avoiding them, and write out
+per-file CSVs plus a Word comparison report.
+"""
+
+from pathlib import Path
+from os import path
+
+import numpy as np
+import pandas as pd
+
+from eso.detection.common_motifs import load_common_motifs
+from eso.detection.dispatch import (
+    collapse_recombination_sites,
+    collapse_slippage_sites,
+    find_recombination_candidates,
+    find_slippage_candidates,
+    recombination_sites_for_constraints,
+    slippage_sites_for_constraints,
+)
+from eso.detection.methylation import load_motifs, find_motif_sites
+from eso.io_utils import file_opener, file_stem, relevant_file_paths, test_input
+from eso.optimize import optimization_engine
+from eso.report import create_word_document_with_highlighted_differences
+from eso.sequence_utils import parse_region
+
+
+def suspect_site_extractor(target_seq, compute_motifs, num_sites, motifs_path=None,
+                            common_motifs=None, recombination_mode='thorough',
+                            slippage_mode='default'):
+    """Detect recombination and slippage sites (and, if `compute_motifs`, methylation
+    motif sites) in `target_seq`. Returns a dict of dataframes keyed by
+    'df_recombination', 'df_slippage', and optionally 'df_motifs' - each
+    collapsed to one representative per distinct site and limited to
+    `num_sites`, for reporting - plus 'df_recombination_raw'/'df_slippage_raw',
+    a reduced-but-not-collapsed view (see
+    eso.detection.slippage.slippage_sites_for_constraints) meant for building
+    correction constraints from instead.
+
+    Detection itself only runs once per category; the report and
+    constraint-building views are both derived from that single run. Use the
+    _raw dataframes (not the collapsed ones) to build correction constraints:
+    collapsing (as the report view does) can silently drop a genuinely
+    distinct, only-partially-overlapping hotspot entirely, leaving the region
+    it uniquely covered with no fix. `num_sites` is report-only for the same
+    reason - limiting it would reintroduce that exact silent-coverage-loss
+    risk for whichever candidates it cuts.
+
+    recombination_mode: see eso.detection.dispatch.find_recombination_sites -
+        "thorough" (default, Levenshtein-tolerant) or "fast" (exact-match only).
+    slippage_mode: see eso.detection.dispatch.find_slippage_sites -
+        "default" or "fast" (equivalent sensitivity; "default" is also faster).
+    common_motifs: list of str or None
+        Names from eso.detection.common_motifs.COMMON_MOTIFS (currently
+        "dam", "dcm") to include alongside any `motifs_path` file. At least
+        one of `motifs_path`/`common_motifs` is required if `compute_motifs`.
+    """
+    df_recombination_candidates = find_recombination_candidates(target_seq, mode=recombination_mode)
+    df_slippage_candidates = find_slippage_candidates(target_seq, mode=slippage_mode)
+
+    sites_collector = {
+        'df_recombination': collapse_recombination_sites(
+            df_recombination_candidates, num_sites, mode=recombination_mode),
+        'df_slippage': collapse_slippage_sites(df_slippage_candidates, num_sites, mode=slippage_mode),
+        'df_recombination_raw': recombination_sites_for_constraints(df_recombination_candidates, mode=recombination_mode),
+        'df_slippage_raw': slippage_sites_for_constraints(df_slippage_candidates, mode=slippage_mode),
+    }
+
+    if compute_motifs:
+        relevant_motifs = list(load_motifs(motifs_path)) if motifs_path else []
+        if common_motifs:
+            relevant_motifs = relevant_motifs + load_common_motifs(common_motifs)
+        sites_collector['df_motifs'] = find_motif_sites(target_seq, num_sites, relevant_motifs)
+
+    return sites_collector
+
+
+def _extract_cai(objectives_text_summary, num_codons):
+    """Parse the CAI objective's score out of DNAChisel's summary text, or
+    return None if there wasn't one (e.g. `organism_name` wasn't recognized,
+    so no codon-optimization objective was ever added - DNAChisel then
+    summarizes as "===> No specifications", which has no ':' to parse and
+    used to crash this with an unhandled IndexError).
+    """
+    first_line = objectives_text_summary.split('\n')[0]
+    if ':' not in first_line:
+        return None
+    cai_score = float(first_line.split(':')[1].strip())
+    return np.exp(cai_score / num_codons).round(4)
+
+
+def backend(data, file, output_path, compute_motifs, num_sites, motifs_path,
+            optimize, mini_gc, maxi_gc, method, organism_name, indexes,
+            recombination_mode='thorough', slippage_mode='default', common_motifs=None,
+            custom_score_fn=None, custom_score_minimize=False):
+    """Run the two-pass optimization (CAI/GC only, then + hotspot avoidance) over
+    every sequence record in `data`, and write out CSVs + a Word report to
+    `output_path/<file_stem>/`.
+    """
+    recombination_collector = []
+    recombination_raw_collector = []
+    slippage_collector = []
+    slippage_raw_collector = []
+    motifs_collector = []
+    sequences_for_doc = []
+
+    filename_indexes = file_stem(file[0])
+    curr_output_path = path.join(output_path, filename_indexes)
+    Path(curr_output_path).mkdir(parents=True, exist_ok=True)
+
+    final_results = []
+
+    for ii, record in enumerate(data):
+        curr_seq = str(record.seq).upper()
+        original_seq = curr_seq
+        seq_indexes = str(ii)
+
+        if (filename_indexes, seq_indexes) not in indexes:
+            orf_regions = ()
+            exclusion_regions = ()
+        else:
+            relevant_index_data = indexes[(filename_indexes, seq_indexes)]
+            orf_regions = parse_region(relevant_index_data[0])
+            exclusion_regions = parse_region(relevant_index_data[1])
+
+        num_codons = sum((orf[1] - orf[0]) / 3 for orf in orf_regions) or len(curr_seq) // 3
+
+        maximal_cai = None
+        if optimize:
+            curr_seq, obj_description, _ = optimization_engine(
+                curr_seq, mini_gc=mini_gc, maxi_gc=maxi_gc, method=method, organism_name=organism_name,
+                custom_score_fn=custom_score_fn,
+                custom_score_minimize=custom_score_minimize,
+                orf_regions=orf_regions, exclusion_regions=exclusion_regions)
+            if custom_score_fn is None:
+                maximal_cai = _extract_cai(obj_description, num_codons)
+
+        curr_sites_collector = suspect_site_extractor(
+            curr_seq, compute_motifs, num_sites, motifs_path, common_motifs=common_motifs,
+            recombination_mode=recombination_mode, slippage_mode=slippage_mode)
+
+        # reporting (CSV) uses the collapsed, num_sites-limited view; the
+        # optimizer is given the raw, uncollapsed, unlimited view instead, so a
+        # genuinely distinct hotspot that only partially overlaps a
+        # higher-scoring one still gets its own correction constraint - see
+        # suspect_site_extractor's docstring and docs/detector-comparisons.md.
+        df_recombination = curr_sites_collector['df_recombination']
+        if len(df_recombination) > 0:
+            df_recombination.loc[:, 'sequence_number'] = str(ii)
+            recombination_collector.append(df_recombination)
+        df_recombination_raw = curr_sites_collector['df_recombination_raw']
+        if len(df_recombination_raw) > 0:
+            df_recombination_raw.loc[:, 'sequence_number'] = str(ii)
+            recombination_raw_collector.append(df_recombination_raw)
+
+        df_slippage = curr_sites_collector['df_slippage']
+        if len(df_slippage) > 0:
+            df_slippage.loc[:, 'sequence_number'] = str(ii)
+            slippage_collector.append(df_slippage)
+        df_slippage_raw = curr_sites_collector['df_slippage_raw']
+        if len(df_slippage_raw) > 0:
+            df_slippage_raw.loc[:, 'sequence_number'] = str(ii)
+            slippage_raw_collector.append(df_slippage_raw)
+
+        df_motifs = pd.DataFrame()
+        if compute_motifs:
+            df_motifs = curr_sites_collector['df_motifs']
+            if len(df_motifs) > 0:
+                df_motifs.loc[:, 'sequence_number'] = str(ii)
+                motifs_collector.append(df_motifs)
+
+        if optimize:
+            curr_seq, obj_description, num_edits = optimization_engine(
+                curr_seq, df_recombination=df_recombination_raw, df_slippage=df_slippage_raw, df_motifs=df_motifs,
+                mini_gc=mini_gc, maxi_gc=maxi_gc, method=method, organism_name=organism_name,
+                custom_score_fn=custom_score_fn,
+                custom_score_minimize=custom_score_minimize,
+                orf_regions=orf_regions, exclusion_regions=exclusion_regions)
+
+            with open(path.join(curr_output_path, 'final_sequence.txt'), "w", encoding="utf-8") as text_file:
+                if custom_score_fn is None and maximal_cai is not None:
+                    cai_constrained = _extract_cai(obj_description, num_codons)
+                    text_file.write('The maximal CAI of gene (with no constraints) objective:\n')
+                    text_file.write(f'{maximal_cai}\n')
+                    text_file.write('The CAI of gene (after constraints) objective:\n')
+                    text_file.write(f'{cai_constrained}\n')
+                elif custom_score_fn is None:
+                    text_file.write(
+                        "No codon-usage objective was applied (organism_name wasn't recognized).\n")
+                else:
+                    text_file.write('Optimized using a custom score function instead of CAI/tAI.\n')
+                text_file.write('The number of codons edited due to hypermutable site constraints:\n')
+                text_file.write(f'{num_edits}\n')
+                text_file.write('The final sequence is:\n')
+                for line_start in range(0, len(curr_seq), 70):
+                    text_file.write(curr_seq[line_start:line_start + 70] + '\n')
+
+        sequences_for_doc.append((f"{filename_indexes}_{ii}", original_seq, curr_seq))
+        final_results.append((ii, curr_seq))
+
+    if recombination_collector:
+        pd.concat(recombination_collector, ignore_index=True).to_csv(
+            path.join(curr_output_path, 'recombination_sites.csv'), index=False)
+
+    if optimize and recombination_raw_collector:
+        # every candidate actually given a correction constraint during
+        # optimization, not just the collapsed "one representative per
+        # distinct site" view above - since those two views can now
+        # legitimately differ (see suspect_site_extractor's docstring and
+        # docs/detector-comparisons.md), this is what to check against
+        # final_sequence.txt if a diff shows an edit with no corresponding
+        # row in recombination_sites.csv.
+        pd.concat(recombination_raw_collector, ignore_index=True).to_csv(
+            path.join(curr_output_path, 'recombination_sites_corrected.csv'), index=False)
+
+    if slippage_collector:
+        pd.concat(slippage_collector, ignore_index=True).to_csv(
+            path.join(curr_output_path, 'slippage_sites.csv'), index=False)
+
+    if optimize and slippage_raw_collector:
+        # see the recombination_sites_corrected.csv comment above.
+        pd.concat(slippage_raw_collector, ignore_index=True).to_csv(
+            path.join(curr_output_path, 'slippage_sites_corrected.csv'), index=False)
+
+    if compute_motifs and motifs_collector:
+        pd.concat(motifs_collector, ignore_index=True).to_csv(
+            path.join(curr_output_path, 'motif_sites.csv'), index=False)
+
+    if sequences_for_doc:
+        create_word_document_with_highlighted_differences(sequences_for_doc, curr_output_path)
+
+    return final_results
+
+
+def main(input_folder=None, output_path=None, compute_motifs=False, num_sites=np.inf,
+         motifs_path=None, common_motifs=None, optimize=True, mini_gc=0.3, maxi_gc=0.7,
+         method='use_best_codon', organism_name='not_specified', indexes=None,
+         recombination_mode='thorough', slippage_mode='default', custom_score_fn=None,
+         custom_score_minimize=False):
+    """Optimize every FASTA/GenBank file in `input_folder`, writing per-file CSVs
+    of detected hotspots and the optimized sequence into `output_path`.
+
+    Parameters
+    ----------
+    input_folder: str
+        Directory to scan for .fasta/.fna/.ffn/.faa/.frn/.fa/.gb/.gbk/.genbank
+        files (optionally gzipped), directly inside or one level under it.
+    output_path: str
+        Directory to write results into (one subdirectory per input file).
+    compute_motifs: bool
+        Whether to also detect methylation motif sites (needs `motifs_path` and/or
+        `common_motifs`).
+    num_sites: int or float('inf')
+        Max number of hotspots to report (in the CSVs/collapsed dataframes)
+        per category. Default: all. Does NOT limit how many correction
+        constraints are built during optimization - every detected candidate
+        is always given a constraint, regardless of `num_sites`, since
+        limiting that too could silently leave part of a genuine hotspot
+        unconstrained (see eso.pipeline.suspect_site_extractor).
+    motifs_path: str or None
+        Path to a MEME-minimal-format PSSM file.
+    common_motifs: list of str or None
+        Names from eso.detection.common_motifs.COMMON_MOTIFS (currently "dam",
+        "dcm" - E. coli's methylation systems) to include alongside any
+        `motifs_path` file, with no file needed at all. At least one of
+        `motifs_path`/`common_motifs` is required if compute_motifs=True.
+    optimize: bool
+        Whether to codon/GC-optimize and avoid hotspots, vs. just detect them.
+    mini_gc, maxi_gc: float in [0, 1]
+        Allowed GC-content range within any 50nt window.
+    method: {"use_best_codon", "match_codon_usage", "harmonize_rca"}
+        Codon optimization strategy.
+    organism_name: str
+        Host organism for codon optimization (see eso.optimize._codon_optimization_objectives).
+    indexes: dict
+        Maps (file_stem, seq_index_str) -> (orf_region_string, exclusion_region_string),
+        1-indexed and inclusive, e.g. {("my_gene", "0"): ("1-6, 51-68", "1-6, 50-68")}.
+        Omit or pass {} to treat entire sequences as the ORF with no exclusions.
+    recombination_mode: {"thorough", "fast"}
+        See eso.detection.dispatch.find_recombination_sites. "thorough" (default)
+        catches near-duplicate hotspots and stays roughly linear (confirmed
+        practical up to 1,000,000nt - see docs/detector-comparisons.md);
+        "fast" is exact-match only, 19-34x faster, for workloads where that
+        speed gap actually matters.
+    slippage_mode: {"default", "fast"}
+        See eso.detection.dispatch.find_slippage_sites. Both detect identical
+        hotspots; "default" is also faster at every length tested.
+    custom_score_fn: callable(str) -> float, or None
+        If given, replaces CAI/tAI (organism_name/method) with this scoring
+        function - see eso.custom_score.CustomScore. Most users should use
+        the `--custom-score-file` CLI flag / eso.custom_score.load_custom_score_from_file
+        instead of passing a function directly here.
+    custom_score_minimize: bool
+        See eso.optimize.optimization_engine; only used if custom_score_fn is given.
+
+    Returns
+    -------
+    (message, results) where message is 'Success!' or a validation error, and
+    results is a list of (file, seq_index, optimized_sequence) tuples.
+    """
+    indexes = indexes or {}
+    if output_path is None:
+        output_path = path.join(input_folder or '.', 'output')
+
+    files = relevant_file_paths(input_folder=input_folder)
+    message = test_input(mini_gc, maxi_gc, indexes, files)
+
+    if message != 'Success!':
+        return message, []
+
+    final_results = []
+    for file in files:
+        data = file_opener(file)
+        curr_results = backend(
+            data, file, output_path, compute_motifs, num_sites, motifs_path,
+            optimize=optimize, mini_gc=mini_gc, maxi_gc=maxi_gc, method=method,
+            organism_name=organism_name, indexes=indexes, recombination_mode=recombination_mode,
+            slippage_mode=slippage_mode, common_motifs=common_motifs, custom_score_fn=custom_score_fn,
+            custom_score_minimize=custom_score_minimize)
+        final_results.extend((file, seq_index, seq) for seq_index, seq in curr_results)
+
+    return message, final_results

eso/report.py

@@ -0,0 +1,57 @@
+"""Optional Word-document report showing original vs. optimized sequences
+with per-nucleotide differences highlighted.
+"""
+
+from os import path
+
+try:
+    from docx import Document
+    from docx.enum.text import WD_COLOR_INDEX
+    DOCX_AVAILABLE = True
+except ImportError:
+    DOCX_AVAILABLE = False
+
+
+def create_word_document_with_highlighted_differences(sequences_data, output_path):
+    """
+    Parameters
+    ----------
+    sequences_data: list of (sequence_name, original_seq, final_seq) tuples.
+    output_path: directory in which to save 'sequence_comparison.docx'.
+    """
+    if not DOCX_AVAILABLE:
+        print("python-docx not available (install the 'docx-report' extra), skipping Word document generation")
+        return
+
+    doc = Document()
+    doc.add_heading('Sequence Optimization Results', 0)
+
+    for index, (seq_name, original_seq, final_seq) in enumerate(sequences_data):
+        doc.add_heading(f'Sequence: {seq_name}', level=1)
+
+        doc.add_heading('Original Sequence:', level=2)
+        original_paragraph = doc.add_paragraph()
+
+        doc.add_heading('Final Sequence:', level=2)
+        final_paragraph = doc.add_paragraph()
+
+        for i, char in enumerate(original_seq):
+            run = original_paragraph.add_run(char)
+            if i < len(final_seq) and char != final_seq[i]:
+                run.font.highlight_color = WD_COLOR_INDEX.YELLOW
+
+        for i, char in enumerate(final_seq):
+            run = final_paragraph.add_run(char)
+            if i < len(original_seq) and char != original_seq[i]:
+                run.font.highlight_color = WD_COLOR_INDEX.YELLOW
+
+        # was `if seq_name != sequences_data[-1][0]` - compared by name, so a
+        # sequence whose name happened to match the true last entry's name
+        # (e.g. two files/records that coincidentally share a stem) would
+        # wrongly skip its own page break. Compare by position instead.
+        if index != len(sequences_data) - 1:
+            doc.add_page_break()
+
+    doc_path = path.join(output_path, 'sequence_comparison.docx')
+    doc.save(doc_path)
+    print(f"Word document saved to: {doc_path}")