Scoring#

Block 2 — turn a product into a number. See the guide.

Each evaluator has a paired Pydantic config; pass the config to ThompsonSamplingConfig and the sampler builds the evaluator (and rebuilds it inside each worker when processes > 1).

Evaluator configs#

Pydantic configuration models for evaluators.

class TACTICS.thompson_sampling.core.evaluator_config.LookupEvaluatorConfig(*, evaluator_type='lookup', ref_filename, compound_col='Product_Code', score_col='Scores', default_score=None)[source]#

Configuration for LookupEvaluator.

Looks up pre-computed scores from a CSV file. Primarily used for testing and benchmarking where scores are known in advance.

Fields

Parameters:

ref_filename (str) – Path to CSV file with pre-computed scores. Default: required.
compound_col (str) – Column name for compound identifiers. Default: 'Product_Code'.
score_col (str) – Column name for scores in CSV. Default: 'Scores'.
default_score (float | None) – Score returned for product codes absent from the lookup table. None → np.nan (the sampler skips NaN evaluations). Set to 0.0 for sparse lookup libraries such as DEL read counts, where a combination absent from the measured set is a true non-binder (score 0). Default: None.

class TACTICS.thompson_sampling.core.evaluator_config.DBEvaluatorConfig(*, evaluator_type='db', db_filename, db_prefix='')[source]#

Configuration for DBEvaluator.

Looks up pre-computed scores from a SQLite database. Used for benchmarking with large datasets where database lookups are faster than CSV.

Fields

Parameters:

db_filename (str) – Path to SQLite database file. Default: required.
db_prefix (str) – Prefix for database keys. Default: ''.

class TACTICS.thompson_sampling.core.evaluator_config.FPEvaluatorConfig(*, evaluator_type='fp', query_smiles)[source]#

Configuration for FPEvaluator (Fingerprint Tanimoto similarity).

Calculates Morgan fingerprint Tanimoto similarity to a reference molecule.

Fields

Parameters:: query_smiles (str) – SMILES string of reference molecule. Default: required.

class TACTICS.thompson_sampling.core.evaluator_config.MWEvaluatorConfig(*, evaluator_type='mw')[source]#

Configuration for MWEvaluator (Molecular Weight).

Simple evaluator that calculates molecular weight. Primarily used for testing.

Fields

class TACTICS.thompson_sampling.core.evaluator_config.ROCSEvaluatorConfig(*, evaluator_type='rocs', query_molfile, max_confs=50)[source]#

Configuration for ROCSEvaluator (shape similarity).

Calculates ROCS shape + chemistry overlay score to a reference molecule. Requires OpenEye toolkit.

Fields

Parameters:

query_molfile (str) – Path to reference molecule file (SDF/MOL). Default: required.
max_confs (int) – Maximum conformers to generate with Omega. Default: 50.

class TACTICS.thompson_sampling.core.evaluator_config.FredEvaluatorConfig(*, evaluator_type='fred', design_unit_file, max_confs=50)[source]#

Configuration for FredEvaluator (docking score).

Docks molecules using OpenEye FRED and returns docking scores. Requires OpenEye toolkit.

Fields

Parameters:

design_unit_file (str) – Path to OpenEye design unit file (.oedu). Default: required.
max_confs (int) – Maximum conformers to generate with Omega. Default: 50.

class TACTICS.thompson_sampling.core.evaluator_config.MLClassifierEvaluatorConfig(*, evaluator_type='ml_classifier', model_filename)[source]#

Configuration for MLClassifierEvaluator.

Uses a trained scikit-learn classifier to predict activity scores from Morgan fingerprints.

Fields

Parameters:: model_filename (str) – Path to trained model file (joblib pickle). Default: required.

class TACTICS.thompson_sampling.core.evaluator_config.CustomEvaluatorConfig(*, evaluator_type='custom', scoring_function)[source]#

Configuration for CustomEvaluator.

Uses a user-provided callable scoring function that accepts an RDKit Mol and returns a float.

Fields

Parameters:: scoring_function (Callable[[Any], float]) – Callable that accepts an RDKit Mol and returns a float score. Default: required.

Evaluator classes#

class TACTICS.thompson_sampling.core.evaluators.Evaluator[source]#

Base class for scoring functions.

An evaluator turns one product into one number. The sampler calls evaluate() once per product it decides to test and feeds the score into the reagent posteriors.

Most evaluators are constructed by create_evaluator() from their paired Pydantic config (for example LookupEvaluatorConfig builds a LookupEvaluator), which is also how parallel workers rebuild them. Constructing one directly is fine for single-process use.

Subclasses implement evaluate() and the counter property. A score of NaN means “could not score”; the sampler skips it.

abstractmethod evaluate(mol)[source]#

Score one product.

Parameters:: mol – An RDKit Mol for structure-based evaluators, or the product name (str) for LookupEvaluator and DBEvaluator, which key on the product code.
Returns:: The score. Higher is better in mode="maximize"; lower is better in mode="minimize" (docking).
Return type:: float

abstract property counter#: Number of evaluate() calls so far.

class TACTICS.thompson_sampling.core.evaluators.MWEvaluator[source]#

Score = molecular weight. A smoke-test evaluator; it takes no arguments.

Config: MWEvaluatorConfig.

property counter#: Number of evaluate() calls so far.

evaluate(mol)[source]#

Score one product.

Parameters:: mol – An RDKit Mol for structure-based evaluators, or the product name (str) for LookupEvaluator and DBEvaluator, which key on the product code.
Returns:: The score. Higher is better in mode="maximize"; lower is better in mode="minimize" (docking).
Return type:: float

class TACTICS.thompson_sampling.core.evaluators.FPEvaluator(input_dict)[source]#

Score = Morgan-fingerprint Tanimoto similarity to a query molecule.

Fingerprints are radius 2, 2048 bits (ECFP4-equivalent). Fast, needs no 3D, no licence.

Parameters:: input_dict – {"query_smiles": str} – the reference molecule.

Config: FPEvaluatorConfig.

Raises:: ValueError – if query_smiles does not parse.

property counter#: Number of evaluate() calls so far.

evaluate(rd_mol_in)[source]#

Score one product.

Parameters:: mol – An RDKit Mol for structure-based evaluators, or the product name (str) for LookupEvaluator and DBEvaluator, which key on the product code.
Returns:: The score. Higher is better in mode="maximize"; lower is better in mode="minimize" (docking).
Return type:: float

class TACTICS.thompson_sampling.core.evaluators.ROCSEvaluator(input_dict)[source]#

Score = ROCS shape + colour Tanimoto combo to a 3D query (OpenEye).

Conformers are generated with Omega on the fly (max_confs, default 50; change with set_max_confs()). Slow: use processes > 1. Requires the openeye extra and a licence.

Parameters:: input_dict – {"query_molfile": str} – a 3D query file readable by oechem.oemolistream (SDF, MOL2, OEB).

Config: ROCSEvaluatorConfig.

property counter#: Number of evaluate() calls so far.

set_max_confs(max_confs)[source]#: Set the maximum number of conformers generated by Omega :param max_confs:

evaluate(rd_mol_in)[source]#: Generate conformers with Omega and evaluate the ROCS overlay of conformers to a reference molecule :param rd_mol_in: Input RDKit molecule :return: ROCS Tanimoto Combo score, returns -1 if conformer generation fails

overlay(fit_mol)[source]#: Use ROCS to overlay two molecules :param fit_mol: OEMolecule :return: Combo Tanimoto for the overlay

class TACTICS.thompson_sampling.core.evaluators.LookupEvaluator(input_dictionary)[source]#

Score = a value looked up by product code in a precomputed table.

Used for benchmarking against exhaustive scores and for any workflow where scores already exist. Keyed on the product name (<reagent1>_<reagent2>_...), so the sampler skips product synthesis entirely when this evaluator is active.

Parameters:: input_dict – {"ref_filename": str, "compound_col": str = "Product_Code", "score_col": str = "Scores", "default_score": float | None = None}. ref_filename may be .csv or .parquet. default_score is returned for product codes absent from the table; leave it None (→ NaN, skipped) unless absence has a meaning, e.g. 0.0 for DEL read counts where an unlisted product is a non-binder. A JSON string of the same dict is also accepted.

Config: LookupEvaluatorConfig.

property counter#: Number of evaluate() calls so far.

evaluate(product_name)[source]#

Score one product.

Parameters:: mol – An RDKit Mol for structure-based evaluators, or the product name (str) for LookupEvaluator and DBEvaluator, which key on the product code.
Returns:: The score. Higher is better in mode="maximize"; lower is better in mode="minimize" (docking).
Return type:: float

class TACTICS.thompson_sampling.core.evaluators.DBEvaluator(input_dictionary)[source]#

Score = a value looked up by product code in a sqlitedict database.

Like LookupEvaluator but backed by SQLite, for tables too large to hold in memory. Keyed on the product name, so synthesis is skipped.

Parameters:: input_dict – {"db_filename": str, "db_prefix": str} – db_prefix is prepended to the product name to form the key.

Config: DBEvaluatorConfig.

property counter#: Number of evaluate() calls so far.

evaluate(smiles)[source]#

Score one product.

Parameters:: mol – An RDKit Mol for structure-based evaluators, or the product name (str) for LookupEvaluator and DBEvaluator, which key on the product code.
Returns:: The score. Higher is better in mode="maximize"; lower is better in mode="minimize" (docking).
Return type:: float

class TACTICS.thompson_sampling.core.evaluators.FredEvaluator(input_dict)[source]#

Score = FRED docking score into a prepared receptor (OpenEye).

Lower is better – run with mode="minimize". Conformers via Omega (max_confs, default 50; set_max_confs()). Slow: use processes > 1. Requires the openeye extra and a licence.

Parameters:: input_dict – {"design_unit_file": str} – an .oedu design unit.

Config: FredEvaluatorConfig.

Raises:: FileNotFoundError – if the design unit file does not exist.

property counter#: Number of evaluate() calls so far.

set_max_confs(max_confs)[source]#: Set the maximum number of conformers generated by Omega :param max_confs:

evaluate(mol)[source]#

Score one product.

Parameters:: mol – An RDKit Mol for structure-based evaluators, or the product name (str) for LookupEvaluator and DBEvaluator, which key on the product code.
Returns:: The score. Higher is better in mode="maximize"; lower is better in mode="minimize" (docking).
Return type:: float

class TACTICS.thompson_sampling.core.evaluators.CustomEvaluator(scoring_function)[source]#

Score = whatever your Python function returns.

The simplest way to plug in your own scoring: pass a callable that takes an RDKit Mol and returns a float. Results are cached by canonical SMILES; an exception inside the function yields NaN (the product is skipped, the run continues).

For processes > 1 the callable must be picklable – a module-level function, not a lambda or closure – because each worker rebuilds the evaluator from its config.

Parameters:: scoring_function – Callable[[Mol], float].

Config: CustomEvaluatorConfig.

property counter#: Number of evaluate() calls so far.

evaluate(mol)[source]#: Evaluate a molecule using the user-defined scoring function :param mol: Input RDKit molecule :return: Float score from the custom function, np.nan on failure

class TACTICS.thompson_sampling.core.evaluators.MLClassifierEvaluator(input_dict)[source]#

Score = positive-class probability from a pickled scikit-learn classifier.

The model is loaded with joblib and fed a 2048-bit Morgan fingerprint (radius 2); the score is predict_proba(...)[:, 1].

Parameters:: input_dict – {"model_filename": str} – a joblib/pickle file.

Config: MLClassifierEvaluatorConfig.

property counter#: Number of evaluate() calls so far.

evaluate(mol)[source]#

Score one product.

Parameters:: mol – An RDKit Mol for structure-based evaluators, or the product name (str) for LookupEvaluator and DBEvaluator, which key on the product code.
Returns:: The score. Higher is better in mode="maximize"; lower is better in mode="minimize" (docking).
Return type:: float