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

eso/__init__.py

@@ -0,0 +1,11 @@
+"""ESO - Evolutionary Stability Optimizer.
+
+Detects hypermutable sites (recombination, replication-slippage, and
+methylation-motif hotspots) in engineered DNA sequences and optimizes them
+away using DNAChisel, while preserving the amino-acid translation.
+"""
+
+from eso.pipeline import main, suspect_site_extractor
+from eso.optimize import optimization_engine
+
+__all__ = ["main", "suspect_site_extractor", "optimization_engine"]

eso/cli.py

@@ -0,0 +1,111 @@
+"""Command-line entry point: `eso-optimize --input-folder ... --output-path ...`."""
+
+import argparse
+import sys
+
+import numpy as np
+
+from eso.custom_score import CustomScoreFileError, load_custom_score_from_file
+from eso.io_utils import IndexesFileError, load_indexes_from_file
+from eso.pipeline import main as run_pipeline
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        description="Detect and remove hypermutable sites (recombination, slippage, "
+                    "methylation hotspots) from DNA sequences while preserving translation.")
+    parser.add_argument('--input-folder', default='.', help="Directory containing FASTA/GenBank files.")
+    parser.add_argument('--output-path', default=None, help="Directory to write results into (default: <input-folder>/output).")
+    parser.add_argument('--compute-motifs', action='store_true', help="Also detect methylation motif sites.")
+    parser.add_argument('--motifs-path', default=None, help="Path to a MEME-minimal-format PSSM file (optional - can be used with or instead of --common-motifs).")
+    parser.add_argument('--common-motifs', default=None,
+                        help="Comma-separated common motif names to include, no file needed - see "
+                             "eso.detection.common_motifs.COMMON_MOTIFS for the full list (E. coli methylation: "
+                             "dam, dcm; cryptic ribosome binding: shine_dalgarno; cryptic sigma70 promoter "
+                             "elements: sigma70_minus35, sigma70_minus10), e.g. --common-motifs dam,dcm. "
+                             "At least one of --motifs-path/--common-motifs is required with --compute-motifs.")
+    parser.add_argument('--num-sites', type=float, default=np.inf,
+                        help="Max hotspots to report per category (default: all). Only limits what's "
+                             "written to the CSVs - every detected hotspot always gets a correction "
+                             "constraint during optimization, regardless of this value.")
+    parser.add_argument('--no-optimize', action='store_true', help="Only detect hotspots, skip sequence optimization.")
+    parser.add_argument('--mini-gc', type=float, default=0.3)
+    parser.add_argument('--maxi-gc', type=float, default=0.7)
+    parser.add_argument('--method', default='use_best_codon',
+                        choices=['use_best_codon', 'match_codon_usage', 'harmonize_rca'])
+    parser.add_argument('--organism-name', default='not_specified',
+                        help="Host organism for codon optimization (species name, TaxID, or a custom table name "
+                             "e.g. kompas/human_antibody_heavy_chain/human_antibody_light_chain). Ignored if "
+                             "--custom-score-file is given.")
+    parser.add_argument('--custom-score-file', default=None,
+                        help="Path to a Python file scoring sequences your own way, instead of CAI/tAI - see "
+                             "examples/custom_score_template.py for a copyable starting point. Overrides "
+                             "--organism-name and --method.")
+    parser.add_argument('--custom-score-function', default='score',
+                        help="Name of the scoring function inside --custom-score-file (default: 'score'). "
+                             "Only needed if you renamed it away from the template's default.")
+    parser.add_argument('--custom-score-minimize', action='store_true',
+                        help="Treat a LOWER value from your custom score function as better (default: higher is better).")
+    parser.add_argument('--recombination-mode', default='thorough', choices=['thorough', 'fast'],
+                        help="'thorough' (default): Levenshtein-tolerant, catches near-duplicate hotspots, "
+                             "confirmed practical up to 1,000,000nt (see docs/detector-comparisons.md). "
+                             "'fast': exact-match only, 19-34x faster but misses near-duplicates - "
+                             "use only if that speed gap actually matters for your workload.")
+    parser.add_argument('--slippage-mode', default='default', choices=['default', 'fast'],
+                        help="Both detect identical hotspots; 'default' is also faster at every length "
+                             "tested (see eso.detection.dispatch) - 'fast' is kept as an independent "
+                             "cross-check implementation, not for its speed.")
+    parser.add_argument('--indexes-file', default=None,
+                        help="Path to a JSON file specifying ORF/exclusion regions per sequence - see "
+                             "examples/indexes_template.json for a copyable starting point (region "
+                             "strings are 1-indexed and inclusive, e.g. \"1-6, 51-68\"). Omit to treat "
+                             "entire sequences as the ORF with no exclusions.")
+    return parser
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+
+    common_motifs = [name.strip() for name in args.common_motifs.split(',')] if args.common_motifs else None
+
+    custom_score_fn = None
+    if args.custom_score_file is not None:
+        try:
+            custom_score_fn = load_custom_score_from_file(
+                args.custom_score_file, function_name=args.custom_score_function)
+        except CustomScoreFileError as e:
+            print(str(e), file=sys.stderr)
+            return 1
+
+    indexes = None
+    if args.indexes_file is not None:
+        try:
+            indexes = load_indexes_from_file(args.indexes_file)
+        except IndexesFileError as e:
+            print(str(e), file=sys.stderr)
+            return 1
+
+    message, results = run_pipeline(
+        input_folder=args.input_folder,
+        output_path=args.output_path,
+        compute_motifs=args.compute_motifs,
+        num_sites=args.num_sites,
+        motifs_path=args.motifs_path,
+        common_motifs=common_motifs,
+        optimize=not args.no_optimize,
+        mini_gc=args.mini_gc,
+        maxi_gc=args.maxi_gc,
+        method=args.method,
+        organism_name=args.organism_name,
+        indexes=indexes,
+        recombination_mode=args.recombination_mode,
+        slippage_mode=args.slippage_mode,
+        custom_score_fn=custom_score_fn,
+        custom_score_minimize=args.custom_score_minimize,
+    )
+    print(message)
+    return 0 if message == 'Success!' else 1
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

eso/codon_usage.py

@@ -0,0 +1,96 @@
+"""Codon usage bias (CUB) tables for hosts not covered by python-codon-tables."""
+
+from importlib import resources
+
+import pandas as pd
+from Bio import SeqUtils
+
+
+def cub_c1():
+    codon_usage_table = {
+        'A': {'GCA': 0.13718, 'GCC': 0.432097, 'GCG': 0.264336, 'GCT': 0.166387},
+        '*': {'TAA': 0.265377, 'TAG': 0.181818, 'TGA': 0.552805}, 'W': {'TGG': 1},
+        'R': {'AGA': 0.0973128, 'AGG': 0.153007, 'CGA': 0.128389, 'CGC': 0.304978, 'CGG': 0.209737,
+              'CGT': 0.106575}, 'N': {'AAC': 0.792265, 'AAT': 0.207735},
+        'D': {'GAC': 0.718222, 'GAT': 0.281778}, 'C': {'TGC': 0.710465, 'TGT': 0.289535},
+        'Q': {'CAA': 0.361039, 'CAG': 0.638961}, 'E': {'GAA': 0.250212, 'GAG': 0.749788},
+        'G': {'GGA': 0.142656, 'GGC': 0.506165, 'GGG': 0.184803, 'GGT': 0.166376},
+        'H': {'CAC': 0.650846, 'CAT': 0.349154},
+        'I': {'ATA': 0.0923118, 'ATC': 0.673554, 'ATT': 0.234134},
+        'L': {'CTA': 0.0641845, 'CTC': 0.345609, 'CTG': 0.309073, 'CTT': 0.132086, 'TTA': 0.030553,
+              'TTG': 0.118494}, 'K': {'AAA': 0.180592, 'AAG': 0.819408}, 'M': {'ATG': 1},
+        'F': {'TTC': 0.672764, 'TTT': 0.327236},
+        'P': {'CCA': 0.167124, 'CCC': 0.336275, 'CCG': 0.326667, 'CCT': 0.169935},
+        'Y': {'TAC': 0.757778, 'TAT': 0.242222},
+        'S': {'AGC': 0.234258, 'AGT': 0.0671675, 'TCA': 0.103458, 'TCC': 0.220449, 'TCG': 0.247293,
+              'TCT': 0.127375},
+        'T': {'ACA': 0.154802, 'ACC': 0.406355, 'ACG': 0.307613, 'ACT': 0.131231},
+        'V': {'GTA': 0.0871417, 'GTC': 0.460197, 'GTG': 0.289844, 'GTT': 0.162817},
+    }
+    return codon_usage_table
+
+
+def cub_kompas():
+    """Codon usage table for Komagataella phaffii (Pichia pastoris)."""
+    cub_full = {
+        'Ala': {'GCA': 0.275098, 'GCC': 0.244931, 'GCG': 0.0786548, 'GCT': 0.401316},
+        'Arg': {'AGA': 0.455639, 'AGG': 0.181255, 'CGA': 0.119597, 'CGC': 0.0506672, 'CGG': 0.0522151,
+                'CGT': 0.140626},
+        'Asn': {'AAC': 0.465812, 'AAT': 0.534188},
+        'Asp': {'GAC': 0.382762, 'GAT': 0.617238},
+        'Cys': {'TGC': 0.377246, 'TGT': 0.622754},
+        'Gln': {'CAA': 0.603655, 'CAG': 0.396345},
+        'Glu': {'GAA': 0.594953, 'GAG': 0.405047},
+        'Gly': {'GGA': 0.364371, 'GGC': 0.155831, 'GGG': 0.12228, 'GGT': 0.357518},
+        'His': {'CAC': 0.382548, 'CAT': 0.617452},
+        'Ile': {'ATA': 0.236221, 'ATC': 0.297661, 'ATT': 0.466118},
+        'Leu': {'CTA': 0.122977, 'CTC': 0.0842546, 'CTG': 0.152862, 'CTT': 0.170539, 'TTA': 0.178334,
+                'TTG': 0.291033},
+        'Lys': {'AAA': 0.519264, 'AAG': 0.480736},
+        'Met': {'ATG': 1},
+        'Phe': {'TTC': 0.42216, 'TTT': 0.57784},
+        'Pro': {'CCA': 0.378486, 'CCC': 0.180179, 'CCG': 0.102394, 'CCT': 0.338942},
+        'Ser': {'AGC': 0.104434, 'AGT': 0.158704, 'TCA': 0.208354, 'TCC': 0.174084, 'TCG': 0.0945539,
+                'TCT': 0.259871},
+        'Thr': {'ACA': 0.277392, 'ACC': 0.237645, 'ACG': 0.122946, 'ACT': 0.362017},
+        'Trp': {'TGG': 1},
+        'Tyr': {'TAC': 0.48627, 'TAT': 0.51373},
+        'Val': {'GTA': 0.178012, 'GTC': 0.217067, 'GTG': 0.216627, 'GTT': 0.388294},
+        'END': {'TAA': 0.399841, 'TAG': 0.339428, 'TGA': 0.260731},
+    }
+    # SeqUtils.seq1('END') returns 'X' (undefined amino acid), not '*' (stop) -
+    # without this special case, the stop-codon frequencies silently ended up
+    # filed under the wrong key and were never used for stop-codon scoring.
+    return {('*' if x == 'END' else SeqUtils.seq1(x)): cub_full[x] for x in cub_full}
+
+
+def _load_bundled_csv_cub(data_filename):
+    with resources.files("eso.data").joinpath(data_filename).open("r", encoding="utf-8") as handle:
+        df = pd.read_csv(handle)
+
+    codon_usage_table = df.groupby('aa').apply(
+        lambda x: x.set_index('codon')['freq_within_aa'].to_dict(), include_groups=False
+    ).to_dict()
+
+    if '*' not in codon_usage_table:
+        codon_usage_table['*'] = {'TAA': 0.33, 'TAG': 0.33, 'TGA': 0.34}
+
+    return codon_usage_table
+
+
+def cub_human_antibody_heavy_chain():
+    """Codon usage table for human antibody heavy chain, from the iGEM 2025 dataset."""
+    return _load_bundled_csv_cub("human-antibody-heavy-chain-codon-frequencies.csv")
+
+
+def cub_human_antibody_light_chain():
+    """Codon usage table for human antibody light chain, from the iGEM 2025 dataset."""
+    return _load_bundled_csv_cub("human-antibody-light-chain-codon-frequencies.csv")
+
+
+CODON_USAGE_TABLES = {
+    'C1': cub_c1,
+    'kompas': cub_kompas,
+    'human_antibody_heavy_chain': cub_human_antibody_heavy_chain,
+    'human_antibody_light_chain': cub_human_antibody_light_chain,
+}

eso/constraints.py

@@ -0,0 +1,179 @@
+"""Convert detected hotspot dataframes into DNAChisel AvoidPattern constraints,
+respecting user-specified exclusion (locked) regions.
+"""
+
+import warnings
+from os import path
+
+import dnachisel
+import pandas as pd
+
+from eso.detection.recombination import _generate_neighbors
+
+
+def _warn_unfixable_recombination_pair(start_1, end_1, start_2, end_2):
+    warnings.warn(
+        f"Recombination pair ({start_1}, {end_1}) / ({start_2}, {end_2}) has both sites inside an "
+        "exclusion (locked) region - there is no site left to mutate that would break this pair "
+        "without touching a locked region, so no correction constraint was built for it. This "
+        "recombination hotspot will survive optimization unmodified.",
+        stacklevel=3,
+    )
+
+
+def has_overlap_exclusion(start, end, exclusions):
+    """True if the (start, end) region overlaps any exclusion region.
+
+    (start, end) is exclusive-end throughout this codebase (matches Python
+    slicing, eso.sequence_utils.parse_region's output, and
+    eso.detection.recombination's output after _elongate_sites) - a region
+    ending exactly where another begins shares no actual nucleotide with it,
+    so `<=`/`>=` (not `<`/`>`) is required here to avoid treating merely
+    touching regions as overlapping (the same bug class fixed in
+    eso.detection._overlap.ranges_overlap, found independently in this
+    separate module).
+    """
+    for ex in exclusions:
+        if end <= ex[0] or start >= ex[1]:
+            continue
+        return True
+    return False
+
+
+def _indel_recombinations(row, exclusions):
+    """For an indel-type recombination pair: enforce a change in the smaller
+    region if it doesn't overlap an exclusion; otherwise enforce a change in
+    the larger region's inserted nucleotide (the only edit that doesn't
+    increase the Levenshtein distance further). If BOTH regions overlap an
+    exclusion, there is no site left that can legally be mutated - returns no
+    constraint at all (and warns), rather than the previous behavior of
+    falling through to constrain the smaller region anyway even though it
+    overlaps a locked region, directly contradicting the hard AvoidChanges
+    constraint built for that same region elsewhere (confirmed directly:
+    this could make DNAChisel's constraint-resolution retry loop drop
+    whichever of the two conflicting constraints it happened to reach first
+    - in the worst case, the user's own AvoidChanges lock).
+    """
+    start_small, end_small, sequence_small = row.start_1, row.end_1, row.sequence_1
+    start_large, end_large, sequence_large = row.start_2, row.end_2, row.sequence_2
+    if row.len_1 > row.len_2:
+        start_small, end_small, sequence_small = row.start_2, row.end_2, row.sequence_2
+        start_large, end_large, sequence_large = row.start_1, row.end_1, row.sequence_1
+
+    if not has_overlap_exclusion(start_small, end_small, exclusions):
+        return [(start_small, end_small, sequence_small)]
+
+    if has_overlap_exclusion(start_large, end_large, exclusions):
+        _warn_unfixable_recombination_pair(start_small, end_small, start_large, end_large)
+        return []
+
+    prefix = path.commonprefix([sequence_small, sequence_large])
+    suffix = sequence_small[len(prefix):] if len(prefix) < len(sequence_small) else ''
+    return [(start_large, end_large, prefix + nt + suffix) for nt in ['A', 'C', 'G', 'T']]
+
+
+def _substitution_recombinations(row, exclusions):
+    """For a substitution-type recombination pair: enforce a change in
+    whichever region doesn't overlap an exclusion, at all its single-substitution neighbors.
+    If BOTH regions overlap an exclusion, there is no site left that can
+    legally be mutated - returns no constraint at all (and warns), rather
+    than the previous behavior of falling through to constrain region_2
+    anyway even though it overlaps a locked region (see
+    _indel_recombinations' docstring for the same bug in its sibling
+    function, and why this matters).
+    """
+    start_1, end_1, sequence_1 = row.start_1, row.end_1, row.sequence_1
+    start_2, end_2 = row.start_2, row.end_2
+
+    region_1_excluded = has_overlap_exclusion(start_1, end_1, exclusions)
+    region_2_excluded = has_overlap_exclusion(start_2, end_2, exclusions)
+
+    if region_1_excluded and region_2_excluded:
+        _warn_unfixable_recombination_pair(start_1, end_1, start_2, end_2)
+        return []
+
+    if region_2_excluded:
+        start_2, end_2 = start_1, end_1
+
+    substitution_neighbours, _, _ = _generate_neighbors(sequence_1)
+    return [(start_2, end_2, sub) for sub in substitution_neighbours]
+
+
+def recombination_to_multiple_avoidance_sites(df, exclusion_regions):
+    """Translate detected recombination pairs into individual sites to mutate,
+    such that mutating them breaks the Levenshtein-distance-1 relationship
+    between the pair (see _indel_recombinations / _substitution_recombinations).
+    """
+    df_copy = df[['start_1', 'end_1', 'sequence_1', 'start_2', 'end_2', 'sequence_2']].copy()
+    df_copy.loc[:, 'len_1'] = df_copy.sequence_1.apply(len)
+    df_copy.loc[:, 'len_2'] = df_copy.sequence_2.apply(len)
+
+    recombination_sites = []
+    for ii in range(df_copy.shape[0]):
+        row = df_copy.iloc[ii]
+        if row.len_1 != row.len_2:
+            recombination_sites.extend(_indel_recombinations(row, exclusion_regions))
+        else:
+            recombination_sites.extend(_substitution_recombinations(row, exclusion_regions))
+
+    recombination_sites = sorted(set(recombination_sites))
+    return pd.DataFrame.from_records(data=recombination_sites, columns=['start', 'end', 'sequence'])
+
+
+def exclusion_site_correcter(df, exclusion_regions):
+    """Trim detected sites so they don't overlap any exclusion (locked) region.
+
+    (start, end) is exclusive-end (see has_overlap_exclusion) - a region's
+    exclusive end is itself the first *excluded* position, so trimming a site
+    to stop before an exclusion should set end = region[0] (not
+    region[0] - 1), and trimming to start after one should set
+    start = region[1] (not region[1] + 1). The old `-1`/`+1` didn't corrupt
+    the `sequence` field (it always matched the true substring at the
+    resulting start/end - just a shorter one than necessary), but it did
+    needlessly discard one usable, still-modifiable nucleotide per exclusion
+    boundary.
+    """
+    if exclusion_regions == 'error':
+        return df
+
+    if df.empty:
+        # nothing to correct - and, separately, `df_before.apply(..., axis=1)`
+        # below can't infer a Series result from zero rows and returns an
+        # empty DataFrame instead, which then fails the `.loc[:, 'sequence'] =
+        # ...` assignment with a shape-mismatch ValueError. Confirmed directly:
+        # reachable via recombination_to_multiple_avoidance_sites now
+        # correctly returning empty when every candidate pair's sites are
+        # excluded (see eso.constraints._indel_recombinations/
+        # _substitution_recombinations) - previously latent because that path
+        # never used to return empty.
+        return df
+
+    for region in exclusion_regions:
+        df_before = df[df.start < region[0]]
+        df_before.loc[:, 'end'] = df_before.end.apply(lambda x: int(min(x, region[0])))
+        df_before.loc[:, 'sequence'] = df_before.apply(lambda row: row.sequence[:(row.end - row.start)], axis=1)
+
+        df_after = df[df.end > region[1]]
+        df_after.loc[:, 'start'] = df_after.start.apply(lambda x: int(max(x, region[1])))
+        df_after.loc[:, 'sequence'] = df_after.apply(lambda row: row.sequence[-(row.end - row.start):], axis=1)
+
+        df = pd.concat([df_before, df_after], ignore_index=True)
+
+        # keep at least one codon, so there's still something to modify
+        df = df[df.start < df.end - 2]
+
+    return df.sort_values('start').drop_duplicates().reset_index(drop=True)
+
+
+def convert_df_to_constraints(df):
+    """Convert a {sequence, start, end} dataframe of patterns-to-avoid into
+    DNAChisel AvoidPattern constraints.
+    """
+    if df.shape[0] == 0:
+        return []
+
+    df = df[['sequence', 'start', 'end']].drop_duplicates()
+    return [
+        dnachisel.AvoidPattern(df.loc[idx, 'sequence'], location=(int(df.loc[idx, 'start']), int(df.loc[idx, 'end'])))
+        for idx in df.index
+    ]

eso/custom_score.py

@@ -0,0 +1,170 @@
+"""Wrap an arbitrary user-supplied scoring function as a DNAChisel objective,
+as an alternative to eso.optimize's built-in CodonOptimize (CAI/tAI-style)
+objective.
+"""
+
+import importlib.util
+import warnings
+from os import path
+
+import dnachisel
+
+#: DNA alphabet used to build the dummy sequence that a freshly-loaded custom
+#: score file is test-run against, so authoring mistakes surface immediately
+#: with a plain-English message instead of mid-optimization, deep inside
+#: DNAChisel's internals.
+_VALIDATION_TEST_SEQUENCE = "ATGATGATGATGATGATGATGATGATGATG"  # 30nt, multiple of 3
+
+
+class CustomScore(dnachisel.Specification):
+    """DNAChisel objective that maximizes an arbitrary Python function of the
+    sequence, instead of a codon-usage table.
+
+    `score_fn` is called once on the whole scored region (the full sequence,
+    or `location`, if given) on every trial mutation during `optimize()`.
+    This is always correct, with no assumption about how the score behaves.
+
+    An earlier version of this class also supported a "windowed" mode
+    (calling score_fn per fixed-size chunk and summing), matching how the
+    built-in CAI/tAI codon-usage scoring works. It was removed: benchmarking
+    found no case where it was actually faster than this whole-sequence
+    approach (comparable at best, meaningfully slower at worst, since
+    DNAChisel's own optimizer ends up calling score_fn considerably more
+    often when the objective is chunk-localizable) - see
+    docs/detector-comparisons.md for the full investigation, including an
+    initial, incorrect benchmark that was itself corrected. Windowed mode
+    also carried a real, unpreventable correctness risk: a user-supplied
+    score_fn that doesn't genuinely decompose as a sum over independent
+    chunks (true of most real external/ML models) would silently compute a
+    different, structurally unrelated quantity, with no reliable way to
+    detect this automatically. Given it offered no confirmed benefit and a
+    real risk, it was removed rather than kept as an unverified "maybe
+    faster sometimes" option.
+
+    Parameters
+    ----------
+    score_fn
+        Callable taking a DNA sequence (str) and returning a float, higher is
+        better (pass `minimize=True` if lower is better).
+    location
+        Restrict the objective to a sub-region of the full sequence. Defaults
+        to the whole sequence.
+    minimize
+        If True, `score_fn`'s return value is negated before use, so that a
+        *lower* raw score is treated as better.
+    """
+
+    best_possible_score = None
+
+    def __init__(self, score_fn, location=None, minimize=False, boost=1.0):
+        self.score_fn = score_fn
+        self.location = dnachisel.Location.from_data(location)
+        self.minimize = minimize
+        self.boost = boost
+        warnings.warn(
+            "CustomScore re-evaluates score_fn on the full scored region for "
+            "every trial mutation during optimize(), which can be slow for "
+            "an expensive score_fn or a long sequence.",
+            stacklevel=2,
+        )
+
+    def initialized_on_problem(self, problem, role=None):
+        return self._copy_with_full_span_if_no_location(problem)
+
+    def _score_sequence(self, sequence):
+        score = self.score_fn(sequence)
+        return -score if self.minimize else score
+
+    def evaluate(self, problem):
+        sequence = self.location.extract_sequence(problem.sequence)
+        score = self._score_sequence(sequence)
+        return dnachisel.SpecEvaluation(self, problem, score, locations=[self.location])
+
+    def localized(self, location, problem=None):
+        # The score can't be restricted to a sub-region without changing its
+        # meaning, so always re-evaluate the whole thing.
+        return self
+
+    def label_parameters(self):
+        params = []
+        if self.minimize:
+            params.append(("minimize", "True"))
+        return params
+
+    def short_label(self):
+        return "custom score"
+
+
+class CustomScoreFileError(Exception):
+    """A custom-score file failed to load or didn't behave as expected.
+
+    Raised with a plain-English message aimed at someone who wrote a scoring
+    function but doesn't necessarily know Python packaging or DNAChisel -
+    the goal is that this exception's message alone is enough to fix the
+    problem, without needing to read a traceback through this codebase.
+    """
+
+
+def load_custom_score_from_file(file_path, function_name='score'):
+    """Load a user-authored scoring function from a plain Python file.
+
+    The file is expected to define a function named `function_name`
+    (default: `score`) taking a DNA sequence string and returning a number
+    (higher = better).
+
+    This is the mechanism behind `eso-optimize --custom-score-file`, and is
+    also usable directly from Python. Validates the file eagerly (missing
+    function, wrong type, or an error raised on a short test sequence) and
+    raises `CustomScoreFileError` with a message meant to be read and acted
+    on directly by whoever wrote the scoring file - not a Python expert.
+
+    Returns
+    -------
+    score_fn
+    """
+    if not path.isfile(file_path):
+        raise CustomScoreFileError(
+            f"Can't find the custom score file '{file_path}'. Check the path is correct.")
+
+    module_name = f"eso_custom_score_{abs(hash(file_path))}"
+    spec = importlib.util.spec_from_file_location(module_name, file_path)
+    module = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(module)
+    except Exception as e:
+        raise CustomScoreFileError(
+            f"'{file_path}' could not be loaded - it has an error in it. "
+            f"The error was: {e!r}. Open the file and fix that error, then try again."
+        ) from e
+
+    if not hasattr(module, function_name):
+        raise CustomScoreFileError(
+            f"'{file_path}' doesn't define a function called `{function_name}`. "
+            f"Add a function like:\n\n    def {function_name}(seq):\n        "
+            f"return ...  # a number, higher = better\n\nat the top level of the file."
+        )
+
+    score_fn = getattr(module, function_name)
+    if not callable(score_fn):
+        raise CustomScoreFileError(
+            f"'{function_name}' in '{file_path}' isn't a function - it's a {type(score_fn).__name__}. "
+            f"It needs to be defined with `def {function_name}(seq): ...`."
+        )
+
+    try:
+        result = score_fn(_VALIDATION_TEST_SEQUENCE)
+    except Exception as e:
+        raise CustomScoreFileError(
+            f"Your `{function_name}` function raised an error when tested on the "
+            f"sequence '{_VALIDATION_TEST_SEQUENCE}': {e!r}. Please fix `{function_name}` in "
+            f"'{file_path}' and try again."
+        ) from e
+
+    if not isinstance(result, (int, float)):
+        raise CustomScoreFileError(
+            f"Your `{function_name}` function returned a {type(result).__name__} "
+            f"({result!r}) instead of a number, when tested on '{_VALIDATION_TEST_SEQUENCE}'. "
+            f"Make sure it ends with `return <a number>`."
+        )
+
+    return score_fn

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

@@ -0,0 +1,62 @@
+"codon","aa","freq_within_aa"
+"AAA","K",0.17106890771625763
+"AAC","N",0.7594714010180809
+"AAG","K",0.8289310922837424
+"AAT","N",0.2405285989819191
+"ACA","T",0.12943434417186275
+"ACC","T",0.5700403826283748
+"ACG","T",0.21673262630339096
+"ACT","T",0.08379264689637153
+"AGA","R",0.43589749463791727
+"AGC","S",0.2046131559664699
+"AGG","R",0.1342483204173788
+"AGT","S",0.1721907405814423
+"ATA","I",0.17924610290070087
+"ATC","I",0.5831481169905391
+"ATG","M",1
+"ATT","I",0.23760578010875996
+"CAA","Q",0.2581683882559603
+"CAC","H",0.6585073794740844
+"CAG","Q",0.7418316117440398
+"CAT","H",0.3414926205259156
+"CCA","P",0.28782425102934217
+"CCC","P",0.2818994998460761
+"CCG","P",0.13544528480269685
+"CCT","P",0.2948309643218849
+"CGA","R",0.16089925516939307
+"CGC","R",0.13614816992011966
+"CGG","R",0.0883796430780141
+"CGT","R",0.04442711677717706
+"CTA","L",0.026206128917178287
+"CTC","L",0.18474284070023503
+"CTG","L",0.650439639667887
+"CTT","L",0.0709314014054765
+"GAA","E",0.155225868348273
+"GAC","D",0.7665765599432305
+"GAG","E",0.844774131651727
+"GAT","D",0.23342344005676946
+"GCA","A",0.1905103196159264
+"GCC","A",0.39136229922447413
+"GCG","A",0.17586996262300003
+"GCT","A",0.24225741853659946
+"GGA","G",0.22536749930782912
+"GGC","G",0.2709422535216371
+"GGG","G",0.33501746880940225
+"GGT","G",0.16867277836113156
+"GTA","V",0.07044783682952861
+"GTC","V",0.5208259619800238
+"GTG","V",0.3459984720004027
+"GTT","V",0.06272772919004484
+"TAC","Y",0.5955316210893039
+"TAT","Y",0.4044683789106961
+"TCA","S",0.131283339559025
+"TCC","S",0.31696299978576203
+"TCG","S",0.03795954842314847
+"TCT","S",0.13699021568415234
+"TGC","C",0.29280147822586516
+"TGG","W",1
+"TGT","C",0.7071985217741348
+"TTA","L",0.01891296640686233
+"TTC","F",0.6825539618451454
+"TTG","L",0.04876702290236082
+"TTT","F",0.3174460381548546