SeqOpt

class SeqOpt(mode='impact', model=None, target_class=None, df_seq_ref=None, labels=None, df_scales=None, random_state=None, verbose=False)[source]

Bases: Tool

Sequence Optimizer (SeqOpt) class for multi-objective directed evolution over sequence variants [Breimann24a]. Core class; only the SHAP-guided mode="impact" needs aaanalysis[pro] (mode="importance" and everything else run in a base install).

SeqOpt performs protein engineering, not de novo protein design. The two are distinct paradigms: de novo design builds new proteins from the ground up rather than repurposing an existing one – typically a structure-first deep-learning pipeline such as RFdiffusion [Watson23] (backbone generation) -> ProteinMPNN [Dauparas22] (sequence design) -> AlphaFold [Jumper21] (in-silico validation), reviewed in [Yang26]. Protein engineering instead optimizes an existing sequence through iterative mutation and selection (directed evolution). SeqOpt is the machine-learning-guided flavour [Yang19], [Wittmann21]: a model predicts variant fitness so the search prioritizes which mutations to make – here as a multi-objective evolutionary search.

SeqOpt is the search/optimization counterpart of SeqMut: where SeqMut scores mutations, SeqOpt searches the space of multi-mutation variants of a single wild-type for the trade-off (Pareto) front that best satisfies several objectives at once. It runs a re-implementation of NSGA-II [Deb02] using a model-bound SeqMut as the fitness engine, guided each generation by residue-level model attribution: mode="impact" refits ShapModel under fuzzy labeling, mode="importance" uses the static feat_importance ranking.

The evolutionary machinery is a pure-Python re-implementation of DEAP (a dev/test-only parity oracle; the shipped runtime never imports DEAP). Each run setting selects the equivalent DEAP function:

SeqOpt setting -> DEAP function
SeqOpt (method / parameter = value)	DEAP
`run(...)` driver	`algorithms.eaMuPlusLambda` / `eaMuCommaLambda` / `eaSimple`
`algorithm="nsga2"`	`tools.selNSGA2` (`sortNondominated` + `assignCrowdingDist`)
mating selection	`tools.selTournamentDCD`
`survival="mu_plus_lambda" / "mu_comma_lambda" / "ea_simple"`	`eaMuPlusLambda` / `eaMuCommaLambda` / `eaSimple`
`variation="and" / "or"`	`algorithms.varAnd` / `algorithms.varOr`
`crossover="uniform" / "one_point" / "two_point"`	`tools.cxUniform` / `cxOnePoint` / `cxTwoPoint`
`mutation="substitution"`	`tools.mutUniformInt` (categorical resampling analogue)
`constraints=[...], penalty="delta" / "closest_valid"`	`tools.DeltaPenalty` / `tools.ClosestValidPenalty`
`objectives=[(name, "max"/"min", src)]`	`base.Fitness` `weights` (+1 / -1 per objective) + `toolbox.register("evaluate")`
`df_pareto` output / `hall_of_fame_` / `trajectory_`	`tools.ParetoFront` / `tools.HallOfFame` / `tools.Logbook`
`eval` hypervolume / convergence / spread	`deap.benchmarks.tools.hypervolume` / `convergence` / `diversity`

Rows with no DEAP analogue are the aaanalysis value-add: the SHAP / feat_importance residue guidance (mode), the sequence genome + domain constraints (n_mut_max, region, to_aa), the algorithm="greedy" baseline, and any callable(sequence) objective.

Added in version 1.0.0.

Parameters:

mode (str)
model (Optional[Any])
target_class (Optional[Any])
df_seq_ref (Optional[DataFrame])
labels (Union[Sequence[Union[int, float]], ndarray, Series, None])
df_scales (Optional[DataFrame])
random_state (Optional[int])
verbose (bool)

Methods

`eval`(df_pareto[, ref_point, ref_front])	Evaluate a Pareto front: hypervolume, front size, spread and (optionally) convergence.
`run`(df_seq, df_feat, objectives[, ...])	Run multi-objective directed evolution and return the Pareto front of variants.

__init__(mode='impact', model=None, target_class=None, df_seq_ref=None, labels=None, df_scales=None, random_state=None, verbose=False)[source]

Parameters:

mode (str, default='impact') – Residue-guidance mode. 'impact' refits ShapModel every generation under fuzzy labeling (the new variant’s prediction score as a soft label vs. the balanced reference) and mutates the strongest-feat_impact residues — this is the only SeqOpt feature that needs aaanalysis[pro] (SHAP), imported lazily. 'importance' uses the static feat_importance ranking from df_feat (no SHAP, no refit) and walks positions highest-first (no pro dependency).
model (object, optional) – A fitted classifier exposing predict_proba used as the fitness engine (the delta_pred objective) and, in mode='impact', as the model whose attribution guides the search. Required when an objective uses delta_pred or mode='impact'.
target_class (int or str, optional) – Class whose predicted probability the fitness tracks. None selects the positive class.
df_seq_ref (pd.DataFrame, optional) – Labeled, balanced reference sequences (position-based format) the per-generation ShapModel refit is anchored on. Required for mode='impact'.
labels (array-like, shape (n_ref,), optional) – Binary class labels (1=positive, 0=negative) aligned to df_seq_ref. Required for mode='impact'.
df_scales (pd.DataFrame, optional) – Amino acid scales. Default from load_scales().
random_state (int, optional) – Seed threaded through the evolutionary RNG and ShapModel.
verbose (bool, default=False) – If True, verbose outputs are enabled.