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

eso/detection/staubility_variant.py

@@ -0,0 +1,284 @@
+"""Alternate recombination/slippage detectors, developed independently inside the
+STABLES project (Staubility_Code_shimshi.py) using a different algorithmic
+approach than eso.detection.recombination/slippage:
+
+- Recombination: ngram-counting (CountVectorizer, 16-mers) + exact re-match,
+  vs. the Levenshtein-neighbor generation approach in eso.detection.recombination.
+- Slippage: per-frameshift scan for back-to-back repeats, vs. the
+  find-all-occurrences approach in eso.detection.slippage.
+
+This module also carried a methylation-motif scorer (site_motif_grader/
+calc_max_site) at one point; removed after comparison against
+eso.detection.methylation found it scored candidates by raw sequence
+probability with no background correction, which measurably disagrees with
+(not just runs slower than) eso.detection.methylation's background-corrected
+approach whenever a motif's background isn't uniform - see
+docs/detector-comparisons.md for the full writeup, kept as a historical
+record even though the code itself is gone.
+
+Kept as a separate module rather than merged into the primary detectors -
+these are two independently-arrived-at implementations of the same EFM
+Calculator concept and haven't yet been reconciled into one canonical API.
+"""
+
+import re
+
+import numpy as np
+import pandas as pd
+from sklearn.feature_extraction.text import CountVectorizer
+
+from eso.detection._overlap import collapse_overlapping_intervals, collapse_overlapping_intervals_no_coverage_loss
+
+
+def genome_cutter(start, end, seq):
+    return seq[start:end]
+
+
+def find_recombination_candidates(seq):
+    """ngram-counting variant of recombination (RMD) hotspot detection.
+
+    Unlike eso.detection.recombination's variant, this one never collapses
+    overlapping pairs (it only merges exact back-to-back 16-mer matches into
+    one site, which is a different, lossless operation) - so its output is
+    already the raw/candidate view. Kept as a separate name from
+    find_recombination_sites anyway, for a consistent candidates/collapsed
+    pair of names across both detector implementations - see
+    eso.detection.dispatch.
+    """
+    vectorizer = CountVectorizer(analyzer='char_wb', ngram_range=(16, 16))
+    counter = vectorizer.fit_transform([seq]).toarray()
+
+    sites_recombination = list(np.where(counter > 1)[1])
+    empty_columns = [
+        'start_1', 'end_1', 'sequence', 'start_2', 'end_2',
+        'location_delta', 'site_length', 'log10_prob_recombination_ecoli', 'sequence_number',
+    ]
+    if not sites_recombination:
+        return pd.DataFrame(columns=empty_columns)
+
+    all_sites = vectorizer.get_feature_names_out()
+
+    suspect_recombination = []
+    for site in sites_recombination:
+        curr_seq = all_sites[site]
+        list_regions = [match.span() for match in re.finditer(curr_seq.upper(), seq)]
+        suspect_recombination.extend(list_regions)
+
+    suspect_recombination = sorted(suspect_recombination)
+    df_recombination = pd.DataFrame(suspect_recombination, columns=['start', 'end'])
+
+    # merge back-to-back 16-mer matches (from repeats longer than 16nt) into one site
+    df_recombination.loc[:, 'start_delta'] = df_recombination['start'] - df_recombination['start'].shift()
+    df_recombination.loc[:, 'end_delta'] = df_recombination['end'].shift(-1) - df_recombination['end']
+    df_recombination = df_recombination[(df_recombination.start_delta != 1.0) | (df_recombination.end_delta != 1.0)]
+
+    df_recombination.loc[(df_recombination.end_delta == 1.0), 'end'] = None
+    # `df.loc[:, 'end'] = ...` would silently keep the column's existing float64
+    # dtype (from the None assignment above) even after .astype(int) below;
+    # only whole-column reassignment (df['end'] = ...) actually changes dtype.
+    df_recombination['end'] = df_recombination.loc[:, 'end'].bfill().astype(int) - 1
+    df_recombination = df_recombination[df_recombination.start_delta != 1.0][['start', 'end']]
+
+    df_recombination.loc[:, 'sequence'] = df_recombination.apply(
+        lambda x: genome_cutter(x['start'], x['end'], seq), axis=1)
+
+    df_recombination = df_recombination.merge(df_recombination, on='sequence', suffixes=('_1', '_2'))
+    df_recombination = df_recombination[df_recombination.end_1 < df_recombination.start_2]
+
+    df_recombination.loc[:, 'location_delta'] = df_recombination.start_2 - df_recombination.end_1
+    df_recombination.loc[:, 'site_length'] = df_recombination.end_1 - df_recombination.start_1
+
+    # a=5.8 per Oliveira et al. 2008, Table 3, recA+ row (see
+    # eso.detection.recombination.calc_recombination_score's docstring for
+    # the full story, including why the EFM Calculator's own 8.8 is a
+    # mix-up with a different row/parameter of that same table).
+    a, b, c, alpha = 5.8, 1465.6, 0, 29
+    base = a + df_recombination['location_delta']
+    exponent = -1 * alpha / df_recombination['site_length']
+    scale = df_recombination['site_length'] / (
+        1 + b * df_recombination['site_length'] + c * df_recombination['location_delta'])
+    df_recombination.loc[:, 'log10_prob_recombination_ecoli'] = np.log10((base ** exponent) * scale)
+
+    return df_recombination.sort_values('log10_prob_recombination_ecoli', ascending=False).reset_index(drop=True)
+
+
+def collapse_recombination_sites(df_recombination, num_sites=np.inf):
+    """No-op collapse: this detector never produces overlapping-but-distinct
+    pairs the way eso.detection.recombination's does (it only merges exact
+    back-to-back matches, already handled in find_recombination_candidates),
+    so there is nothing to collapse here - just applies `num_sites` and drops
+    any column that's entirely null.
+
+    The null-column drop happens here (on the num_sites-limited report view),
+    not in find_recombination_candidates, matching the original pre-split
+    behavior exactly: which columns are "entirely null" can differ between
+    the full candidate set and a num_sites-limited subset of it, so doing
+    this before truncating (as an earlier version of this split briefly did)
+    could report a different column set for the same `num_sites` value than
+    before the candidates/collapse split existed.
+    """
+    if num_sites < np.inf:
+        df_recombination = df_recombination.head(int(num_sites))
+
+    for col in df_recombination:
+        if df_recombination[col].isnull().all():
+            del df_recombination[col]
+
+    return df_recombination
+
+
+def recombination_sites_for_constraints(df_recombination):
+    """Identity: this detector never collapses overlapping pairs in the first
+    place (see collapse_recombination_sites), so its raw candidates are
+    already the constraint-building view - kept as a same-named counterpart
+    to eso.detection.recombination's version so eso.detection.dispatch can
+    call either implementation uniformly.
+    """
+    return df_recombination
+
+
+def find_recombination_sites(seq, num_sites=np.inf):
+    """ngram-counting variant of recombination (RMD) hotspot detection,
+    limited to `num_sites` if given. See find_recombination_candidates -
+    this detector never needs to collapse, so this is only a thin
+    num_sites-limiting wrapper.
+    """
+    return collapse_recombination_sites(find_recombination_candidates(seq), num_sites)
+
+
+def find_slippage_sites_length_l(seq, length):
+    """Per-frameshift scan for a repeated base unit of size `length`
+    (repeated 3+ times, or 12+ times for length=1 - see
+    eso.detection.slippage's module docstring for why 12: below that, an
+    independently-run length-2 detection of the same physical region always
+    outscores it, so its result is always discarded downstream).
+    """
+    from textwrap import wrap
+
+    slippage_sites = []
+    homopolymer_window = 12
+
+    for frameshift in range(length):
+        curr_seq = seq[frameshift:]
+        curr_seq_split = wrap(curr_seq, length)
+
+        end_of_range = len(curr_seq_split) - 2
+
+        for ii in range(end_of_range):
+            # `length == 1` must be checked FIRST so Python's `and`
+            # short-circuits before touching curr_seq_split[ii + 1/2] when
+            # length > 1 (needed for is_followed2 below); is_followed1 itself
+            # uses slicing, which never raises IndexError even past the list
+            # end, so it needs no equivalent bounds bug to worry about - a
+            # slice shorter than `homopolymer_window` just fails the length
+            # check instead of crashing.
+            is_followed2 = (
+                length > 1
+                and curr_seq_split[ii] == curr_seq_split[ii + 1]
+                and curr_seq_split[ii] == curr_seq_split[ii + 2]
+            )
+            window = curr_seq_split[ii:ii + homopolymer_window]
+            is_followed1 = length == 1 and len(window) == homopolymer_window and len(set(window)) == 1
+
+            if is_followed2:
+                slippage_sites.append((frameshift + ii * length, frameshift + length * (ii + 3)))
+            if is_followed1:
+                slippage_sites.append((ii, ii + homopolymer_window))
+
+    if not slippage_sites:
+        return pd.DataFrame(columns=['start', 'end', 'sequence', 'length_base_unit'])
+
+    df_slippage = pd.DataFrame(sorted(slippage_sites), columns=['start', 'end'])
+
+    df_slippage.loc[:, 'start_delta'] = df_slippage['start'] - df_slippage['start'].shift()
+    df_slippage.loc[:, 'end_delta'] = df_slippage['end'].shift(-1) - df_slippage['end']
+    df_slippage = df_slippage[(df_slippage.start_delta != 1.0) | (df_slippage.end_delta != 1.0)]
+    df_slippage.loc[(df_slippage.end_delta == 1.0), 'end'] = None
+    # see the identical fix in find_recombination_sites above: whole-column
+    # reassignment is required for .astype(int) to actually stick here
+    df_slippage['end'] = df_slippage.loc[:, 'end'].bfill().astype(int)
+    df_slippage = df_slippage[df_slippage.start_delta != 1.0][['start', 'end']]
+
+    df_slippage.loc[:, 'end'] = (
+        ((df_slippage['end'] - df_slippage['start']) / length).astype(int) * length
+    ) + df_slippage['start']
+
+    df_slippage.loc[:, 'sequence'] = df_slippage.apply(
+        lambda x: genome_cutter(x['start'], x['end'], seq), axis=1)
+    df_slippage.loc[:, 'length_base_unit'] = length
+
+    return df_slippage
+
+
+def find_slippage_candidates(seq):
+    """ngram/frameshift-scan variant of slippage (SSR) hotspot detection -
+    every candidate, WITHOUT collapsing overlapping ones down to one
+    representative per physical site. See
+    eso.detection.slippage.find_slippage_candidates for why constraint-
+    building must use this, not find_slippage_sites.
+    """
+    slippage_sites_list = [find_slippage_sites_length_l(seq, length) for length in range(1, 16)]
+    df_slippage = pd.concat(slippage_sites_list, ignore_index=True)[['start', 'end', 'length_base_unit', 'sequence']]
+
+    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']
+    )
+
+    # this filter was applied by the STABLES caller (STABLES_full_code's
+    # optimization pipeline), not inside find_slippage_sites itself - lost
+    # when this function was extracted in isolation. Restored here so the
+    # function is self-contained and consistent with its sibling
+    # find_recombination_candidates above, which does filter internally.
+    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, WITHOUT the coverage-loss
+    risk plain non-max suppression (collapse_slippage_sites) has - see
+    eso.detection.slippage.slippage_sites_for_constraints for the concrete
+    failure this avoids. Kept as a same-named counterpart so
+    eso.detection.dispatch can call either implementation uniformly.
+    """
+    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). See
+    eso.detection.slippage's version of this function for why exact-start
+    dedup isn't enough - phase-shifted/differently-lengthed detections of the
+    same physical repeat need an overlap-based collapse 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):
+    """ngram/frameshift-scan variant of slippage (SSR) hotspot detection,
+    collapsed to one representative per physical site and limited to
+    `num_sites` if given - the human-facing report/count view. Do NOT use
+    this to build correction constraints (see find_slippage_candidates).
+    """
+    return collapse_slippage_sites(find_slippage_candidates(seq), num_sites)
+
+
+def suspect_site_extractor(seq, num_sites=np.inf, extension=''):
+    """Run both recombination and slippage detection (this module's ngram/frameshift variants)."""
+    return {
+        'df_recombination' + extension: find_recombination_sites(seq, num_sites),
+        'df_slippage' + extension: find_slippage_sites(seq, num_sites),
+    }

eso/io_utils.py

@@ -0,0 +1,312 @@
+"""FASTA/GenBank file discovery and input validation."""
+
+import gzip
+import json
+import os
+from os import path
+from pathlib import Path
+
+from Bio import SeqIO
+from dnachisel import biotools
+
+from eso.sequence_utils import parse_region
+
+FILE_ENDINGS = {
+    'fasta': ['fasta', 'fna', 'ffn', 'faa', 'frn', 'fa'],
+    'genbank': ['genbank', 'gb', 'gbk'],
+}
+
+
+def file_stem(filepath):
+    """Basename with its extension(s) removed, preserving any other dots in
+    the stem itself. `path.basename(filepath).split('.')[0]` (used to
+    determine this) truncated at the FIRST dot, so a filename like
+    "sample.2024.fasta" silently became the stem "sample" instead of
+    "sample.2024" - meaning an `indexes` entry keyed on the intended full
+    stem would never match, silently falling back to no ORF/exclusion
+    regions instead of erroring.
+    """
+    name = path.basename(filepath)
+    if name.endswith('.gz'):
+        name = name[:-3]
+    return path.splitext(name)[0]
+
+
+class IndexesFileError(Exception):
+    """An --indexes-file failed to load or was malformed.
+
+    Raised with a plain-English message aimed at someone filling in ORF and
+    exclusion regions for their sequences, not a Python or JSON expert - the
+    message alone should be enough to fix the problem.
+    """
+
+
+def load_indexes_from_file(file_path):
+    """Load the `indexes` argument to eso.pipeline.main from a JSON file, for
+    use as the CLI's `--indexes-file`.
+
+    The file must be a JSON list of objects, each with:
+    - "file": the FASTA/GenBank file's stem (no extension - matches
+      eso.io_utils.file_stem), e.g. "my_gene" for "my_gene.fasta".
+    - "seq_index": which record within that file, as a string, 0-indexed in
+      file order, e.g. "0" for the first sequence.
+    - "orf_regions": 1-indexed, inclusive region string, e.g. "1-6, 51-68".
+    - "exclusion_regions": same format; omit or use "" for no exclusions.
+
+    Region strings themselves are validated later, the same way as when
+    `indexes` is passed directly to eso.pipeline.main - this only checks the
+    file's own structure (valid JSON, a list, well-formed entries).
+
+    Returns
+    -------
+    dict mapping (file_stem, seq_index) -> (orf_regions, exclusion_regions),
+    matching eso.pipeline.main's `indexes` parameter.
+    """
+    if not path.isfile(file_path):
+        raise IndexesFileError(
+            f"Can't find the indexes file '{file_path}'. Check the path is correct.")
+
+    with open(file_path, "r", encoding="utf-8") as handle:
+        try:
+            entries = json.load(handle)
+        except json.JSONDecodeError as e:
+            raise IndexesFileError(
+                f"'{file_path}' isn't valid JSON: {e}. Check for missing commas, quotes, or brackets."
+            ) from e
+
+    if not isinstance(entries, list):
+        raise IndexesFileError(
+            f"'{file_path}' must contain a JSON list of entries (got a {type(entries).__name__} instead). "
+            'Each entry looks like {"file": "my_gene", "seq_index": "0", "orf_regions": "1-6, 51-68", '
+            '"exclusion_regions": "1-6, 50-68"}.')
+
+    indexes = {}
+    for ii, entry in enumerate(entries):
+        if not isinstance(entry, dict) or 'file' not in entry or 'seq_index' not in entry:
+            raise IndexesFileError(
+                f"Entry {ii} of '{file_path}' must be an object with at least \"file\" and "
+                f'"seq_index" keys - got {entry!r}.')
+
+        key = (str(entry['file']), str(entry['seq_index']))
+        orf_regions = str(entry.get('orf_regions', ''))
+        exclusion_regions = str(entry.get('exclusion_regions', ''))
+        indexes[key] = (orf_regions, exclusion_regions)
+
+    return indexes
+
+
+def file_opener(file):
+    """`file` is a (filepath, filetype) tuple, filetype in {'fasta', 'genbank'}."""
+    filepath, filetype = file
+    if filepath.endswith('.gz'):
+        with gzip.open(filepath, "rt", encoding="utf-8") as handle:
+            return list(SeqIO.parse(handle, filetype))
+    with open(filepath, "rt", encoding="utf-8") as handle:
+        return list(SeqIO.parse(handle, filetype))
+
+
+def _matching_filetype(filename):
+    """Return the FILE_ENDINGS key `filename` belongs to (case-insensitively,
+    ignoring a trailing .gz), or None if it doesn't match any known extension.
+
+    Matching case-insensitively (rather than relying on glob('*.fasta')) matters
+    because glob's case sensitivity is filesystem-dependent - Windows filesystems
+    are case-insensitive so `*.fasta` there also matches `GENE.FASTA`, but the
+    same glob call on a (case-sensitive) Mac/Linux filesystem would silently skip
+    it. Confirmed this is a real, reachable discrepancy, not hypothetical -
+    without this, a file discovery result depends on which OS the tool happens
+    to run on for the exact same input folder.
+    """
+    name = filename.lower()
+    if name.endswith('.gz'):
+        name = name[:-3]
+    if '.' not in name:
+        return None
+    ext = name.rsplit('.', 1)[-1]
+    for filetype, endings in FILE_ENDINGS.items():
+        if ext in endings:
+            return filetype
+    return None
+
+
+def relevant_file_paths(input_folder=None):
+    """Find all FASTA/GenBank files (optionally gzipped) directly in or one level
+    under `input_folder`, returned as a list of (filepath, filetype) tuples.
+    """
+    if input_folder is None:
+        input_folder = os.getcwd()
+    input_as_path = Path(input_folder)
+
+    candidates = [p for p in input_as_path.glob('*') if p.is_file()]
+    for entry in input_as_path.glob('*'):
+        if entry.is_dir():
+            candidates.extend(p for p in entry.glob('*') if p.is_file())
+
+    files = []
+    for candidate in candidates:
+        filetype = _matching_filetype(candidate.name)
+        if filetype is not None:
+            files.append((str(candidate), filetype))
+    return files
+
+
+def exclusion_gc_tester(file, indexes):
+    """Given a file's exclusion (locked) regions, compute the range of GC-content
+    limits that can still legally be enforced across a sliding window that
+    partially overlaps those regions.
+    """
+    data = file_opener(file)
+    filename_indexes = file_stem(file[0])
+
+    legal_mini_gc = 1.0
+    legal_maxi_gc = 0.0
+
+    for ii, record in enumerate(data):
+        example_seq = str(record.seq).upper()
+        windowed_gc_content = biotools.gc_content(example_seq, window_size=50)
+        seq_indexes = str(ii)
+
+        if (filename_indexes, seq_indexes) not in indexes:
+            exclusion_regions = ()
+        else:
+            relevant_index_data = indexes[(filename_indexes, seq_indexes)]
+            exclusion_regions = parse_region(relevant_index_data[1])
+
+        for region in exclusion_regions:
+            start_ind, end_ind = region
+            curr_min_gc, curr_max_gc = 1.0, 0.0
+
+            if start_ind + 50 <= end_ind:
+                curr_max_gc = max(windowed_gc_content[start_ind:end_ind - 50])
+                curr_min_gc = min(windowed_gc_content[start_ind:end_ind - 50])
+
+            for jj in range(50):
+                if start_ind - jj < 0:
+                    break
+                curr_region = (start_ind - jj, start_ind + 49 - jj)
+                overlap = ''
+                for ex_reg in exclusion_regions:
+                    overlap_reg = biotools.windows_overlap(curr_region, ex_reg)
+                    if overlap_reg is not None:
+                        overlap += example_seq[overlap_reg[0]:overlap_reg[1]]
+                # biotools.gc_content('') is 0/0 (NaN, with a RuntimeWarning) -
+                # `overlap` is empty whenever none of exclusion_regions actually
+                # overlaps this particular sliding window, which does happen (e.g.
+                # a window entirely before the region under test). The GC content
+                # of an empty overlap contributes nothing regardless, so skip the
+                # call rather than asking for a GC content that doesn't exist.
+                curr_gc = biotools.gc_content(overlap) if overlap else 0.0
+                curr_max_gc = max(curr_max_gc, curr_gc * len(overlap) / 50.0)
+                curr_min_gc = min(curr_min_gc, curr_gc * len(overlap) / 50.0 + (1.0 - len(overlap) / 50.0))
+
+            for jj in range(50):
+                if end_ind + jj >= len(example_seq):
+                    break
+                curr_region = (end_ind - 49 + jj, end_ind + jj)
+                overlap = ''
+                for ex_reg in exclusion_regions:
+                    overlap_reg = biotools.windows_overlap(curr_region, ex_reg)
+                    if overlap_reg is not None:
+                        overlap += example_seq[overlap_reg[0]:overlap_reg[1]]
+                curr_gc = biotools.gc_content(overlap) if overlap else 0.0
+                curr_max_gc = max(curr_max_gc, curr_gc * len(overlap) / 50.0)
+                curr_min_gc = min(curr_min_gc, curr_gc * len(overlap) / 50.0 + (1.0 - len(overlap) / 50.0))
+
+            legal_mini_gc = min(curr_min_gc, legal_mini_gc)
+            legal_maxi_gc = max(curr_max_gc, legal_maxi_gc)
+
+    return legal_mini_gc, legal_maxi_gc
+
+
+def _sequence_lengths_by_index_key(files):
+    """Map (file_stem, seq_index_str) -> sequence length, for every record in
+    `files` - lets ORF/exclusion regions be checked against the actual
+    sequence they'll apply to, not just against each other.
+    """
+    lengths = {}
+    for file in files:
+        filename_indexes = file_stem(file[0])
+        for ii, record in enumerate(file_opener(file)):
+            lengths[(filename_indexes, str(ii))] = len(record.seq)
+    return lengths
+
+
+def test_input(mini_gc, maxi_gc, indexes, files):
+    """Validate GC-content bounds and ORF/exclusion region formatting before running.
+
+    `indexes` maps (filename, seq_index) -> (orf_region_string, exclusion_region_string),
+    e.g. {"myfile": ("1-9, 21-29", "")} - 1-indexed, inclusive, as entered by a biologist.
+    """
+    if mini_gc < 0.0:
+        return 'The minimal GC content must be at least 0!'
+    if maxi_gc > 1.0:
+        return 'The maximal GC content must be no more than 1!'
+    if mini_gc >= maxi_gc:
+        return 'The minimal GC content must be less than the maximum!'
+
+    if len(indexes) > 0:
+        # only checked against a record when the (file, seq_index) key
+        # actually matches one - an unmatched key is a separate, pre-existing
+        # leniency (eso.io_utils.file_stem's docstring, eso.pipeline.backend's
+        # `if key not in indexes` check) this doesn't attempt to change.
+        seq_lengths = _sequence_lengths_by_index_key(files)
+
+        for key, index_value in indexes.items():
+            seq_length = seq_lengths.get(key)
+
+            orf_indexes = parse_region(index_value[0])
+            if orf_indexes == 'error':
+                return 'ORF regions must be formatted as "start_1-end_1,start_2-end_2,...", for example "1-9, 21-29"'
+            for curr_ind in orf_indexes:
+                if curr_ind[0] < 0:
+                    return 'Start index must be greater than 0!'
+                if curr_ind[0] >= curr_ind[1]:
+                    return 'Start index must be smaller than end index!'
+                if (curr_ind[1] - curr_ind[0]) % 3 != 0:
+                    return 'Indexes must describe sequence length divisible by 3!'
+                # without this, an ORF region's end past the actual sequence
+                # length isn't rejected here - Python's forgiving slicing
+                # (seq[0:6000] on a 500nt string just returns 500nt) means a
+                # region meant for a different/longer sequence would silently
+                # get truncated instead of erroring, with no indication the
+                # requested region wasn't what was actually applied.
+                if seq_length is not None and curr_ind[1] > seq_length:
+                    return (
+                        f'ORF region {curr_ind[0] + 1}-{curr_ind[1]} (1-indexed) goes past the end of '
+                        f'{key[0]!r} sequence {key[1]} ({seq_length}nt long)!'
+                    )
+
+            if index_value[1] not in ('', 'None'):
+                region_indexes = parse_region(index_value[1])
+                if region_indexes == 'error':
+                    return 'Exclusion regions must be formatted as "start_1-end_1,start_2-end_2,...", for example "1-8, 50-103"'
+                # was `for curr_ind in orf_indexes` - validated the already-checked
+                # ORF indexes a second time and never actually checked the
+                # exclusion regions themselves, so a malformed exclusion region
+                # (e.g. start >= end) slipped through validation entirely and
+                # only surfaced later as a confusing, unrelated GC-limit error.
+                for curr_ind in region_indexes:
+                    if curr_ind[0] < 0:
+                        return 'Start index must be greater than 0, also for exclusion sites!!'
+                    if curr_ind[0] >= curr_ind[1]:
+                        return 'Start index must be smaller than end index, also for exclusion sites!'
+                    if seq_length is not None and curr_ind[1] > seq_length:
+                        return (
+                            f'Exclusion region {curr_ind[0] + 1}-{curr_ind[1]} (1-indexed) goes past the end '
+                            f'of {key[0]!r} sequence {key[1]} ({seq_length}nt long)!'
+                        )
+
+        legal_mini_gc, legal_maxi_gc = 0.0, 1.0
+        for file in files:
+            curr_mini_gc, curr_maxi_gc = exclusion_gc_tester(file, indexes)
+            legal_mini_gc = max(legal_mini_gc, curr_mini_gc) + 0.01
+            legal_maxi_gc = min(legal_maxi_gc, curr_maxi_gc) - 0.01
+
+        if legal_mini_gc < mini_gc or legal_maxi_gc > maxi_gc:
+            return (
+                f'Given the exclusion regions defined by the user, the maximal GC limit must be at least '
+                f'{legal_maxi_gc} and the minimal GC limit must be at most {legal_mini_gc}. Note that the '
+                f'maximal/minimal GC limit required might be a bit higher/lower to account also for ORF regions.'
+            )
+
+    return 'Success!'