improved documentation

molgenevalmetric.py

@@ -4,19 +4,25 @@ import datasets
 import pandas as pd
 import numpy as np
 import scipy.sparse
+from scipy.spatial.distance import cosine as cos_distance
+from scipy.stats import wasserstein_distance
 import torch
 import warnings
 from multiprocessing import Pool
 from functools import partial
 from fcd_torch import FCD
+from collections import Counter
+
 
 from tdc import Oracle
 from rdkit.Chem.Crippen import MolLogP
 from rdkit import Chem
 from rdkit.Chem import MACCSkeys
+from rdkit.Chem import AllChem
 from rdkit.Chem.AllChem import GetMorganFingerprintAsBitVect as Morgan
 from rdkit.Chem.QED import qed
 from rdkit.Contrib.SA_Score import sascorer
+from rdkit.Chem.Scaffolds import MurckoScaffold
 
 from syba.syba import SybaClassifier
 from myscscore.SCScore import SCScorer
@@ -157,6 +163,9 @@ def novelty(gen, train, n_jobs=1):
 def synthetic_complexity_score(gen):
     """
     Calculate the average Synthetic Complexity Score (SCScore) for a list of molecules represented by their SMILES strings.
+    The SCScore model rates the synthetic complexity of molecules on a scale from 1 to 5. 
+    Based on the premise that on average, the products of published chemical reactions should be more synthetically complex than their corresponding reactants
+
 
     Parameters:
     - gen (list of str): A list containing the SMILES representations of the molecules.
@@ -174,7 +183,10 @@ def synthetic_complexity_score(gen):
 def calculate_sa_score(smiles):
     """
     Calculates the SA score for a single SMILES string.
-    
+    Evaluates the ease of synthesizing drug-like molecules in virtual screening. 
+    Ranges from 1 (easy to synthesize) to 10 (hard to synthesize)
+    This score reflects the presence of common fragments in a molecule and structural complexities.
+
     Parameters:
     - smiles (str): SMILES string of the molecule.
     
@@ -189,11 +201,10 @@ def calculate_sa_score(smiles):
 
 def average_sascore(gen, n_jobs=1):
     """
-    Computes the average synthetic accessibility score for a list of molecules
-    using parallel or sequential execution based on the n_jobs parameter.
+    Computes the average synthetic accessibility score for a list of molecules.
 
     Parameters:
-    - molecules (List[str]): List of generated SMILES strings.
+    - gen (List[str]): List of generated SMILES strings.
     - n_jobs (int): Number of parallel jobs to use for computation.
 
     Returns:
@@ -358,6 +369,8 @@ def internal_diversity(gen, n_jobs=1, device='cpu', fp_type='morgan',
 def fcd_metric(gen, train, n_jobs = 1, device = None):
     """
     Computes the Fréchet ChemNet Distance (FCD) between two sets of molecules.
+    FCD is calculated using the Fréchet Distance between feature vectors of generated and real molecules obtained from ChemNet.
+    A lower FCD score indicates higher chemical realism and diversity in the molecules generated by a model.
 
     Parameters:
     - gen (List[str]): List of generated SMILES strings.
@@ -380,10 +393,13 @@ def fcd_metric(gen, train, n_jobs = 1, device = None):
 
 def SYBAscore(gen):
     """
-    Compute the average SYBA score for a list of SMILES strings.
+    Compute the average SYBA (SYnthetic Bayesian Accessibility) score for a list of SMILES strings.
+    It is a fragment-based method for the rapid classification of organic compounds as easy- (ES) or hard-to-synthesize (HS). 
+    Based on a Bernoulli naïve Bayes classifier that is used to assign SYBA score contributions to individual fragments based on their frequencies in the database of ES and HS molecules.
+    Trained on ES molecules available in the ZINC15 database and on HS molecules generated by the Nonpher methodology
 
     Parameters:
-    - smiles_list (list of str): A list of SMILES strings representing molecules.
+    - gen (List[str]): List of generated SMILES strings.
 
     Returns:
     - float: The average SYBA score for the list of molecules.
@@ -407,7 +423,18 @@ def SYBAscore(gen):
 
 def qed_metric(gen):
     """
-    Computes RDKit's QED score
+    Computes RDKit's QED score.
+    A [0,1] value estimating how likely a molecule is a viable candidate for a drug. 
+    QED is meant to capture certain desirable traits that successful drug molecules tend to possess 
+
+
+
+    Parameters:
+    - gen (List[str]): List of generated SMILES strings.
+
+    Returns:
+    - float: The average QED score for the list of molecules.
+
     """
     if not gen:
         return 0.0  # Return 0 or suitable value for empty list
@@ -433,7 +460,7 @@ def logP_metric(gen):
     Computes the average RDKit's logP value for a list of SMILES strings.
 
     Parameters:
-    - mols (List[str]): List of SMILES strings representing the molecules.
+    - gen (List[str]): List of generated SMILES strings.
 
     Returns:
     - float: Average logP value for the list of molecules.
@@ -463,7 +490,7 @@ def penalized_logp(gen):
     Computes the average PyTDC's penalized logP value for a list of SMILES strings.
 
     Parameters:
-    - mols (List[str]): List of SMILES strings representing the molecules.
+    - gen (List[str]): List of generated SMILES strings.
 
     Returns:
     - float: Average penalized logP value for the list of molecules.
@@ -477,8 +504,6 @@ def penalized_logp(gen):
     return score
 
 
-
-
 _DESCRIPTION = """
 
 Comprehensive suite of metrics designed to assess the performance of molecular generation models, for understanding how well a model can produce novel, chemically valid molecules that are relevant to specific research objectives.
@@ -541,3 +566,146 @@ class molgenevalmetric(evaluate.Metric):
 
         return metrics
 
+
+# def get_n_rings(mol):
+#     """
+#     Computes the number of rings in a molecule
+#     """
+#     return mol.GetRingInfo().NumRings()
+
+# def fragmenter(mol):
+#     """
+#     fragment mol using BRICS and return smiles list
+#     """
+#     fgs = AllChem.FragmentOnBRICSBonds(get_mol(mol))
+#     fgs_smi = Chem.MolToSmiles(fgs).split(".")
+#     return fgs_smi
+
+# def compute_fragments(mol_list, n_jobs=1):
+#     """
+#     fragment list of mols using BRICS and return smiles list
+#     """
+#     fragments = Counter()
+#     for mol_frag in mapper(n_jobs)(fragmenter, mol_list):
+#         fragments.update(mol_frag)
+#     return fragments
+
+# def compute_scaffolds(mol_list, n_jobs=1, min_rings=2):
+#     """
+#     Extracts a scafold from a molecule in a form of a canonic SMILES
+#     """
+#     scaffolds = Counter()
+#     map_ = mapper(n_jobs)
+#     scaffolds = Counter(
+#         map_(partial(compute_scaffold, min_rings=min_rings), mol_list))
+#     if None in scaffolds:
+#         scaffolds.pop(None)
+#     return scaffolds
+
+# def compute_scaffold(mol, min_rings=2):
+#     mol = get_mol(mol)
+#     try:
+#         scaffold = MurckoScaffold.GetScaffoldForMol(mol)
+#     except (ValueError, RuntimeError):
+#         return None
+#     n_rings = get_n_rings(scaffold)
+#     scaffold_smiles = Chem.MolToSmiles(scaffold)
+#     if scaffold_smiles == '' or n_rings < min_rings:
+#         return None
+#     return scaffold_smiles
+
+# class Metric:
+#     def __init__(self, n_jobs=1, device='cpu', batch_size=512, **kwargs):
+#         self.n_jobs = n_jobs
+#         self.device = device
+#         self.batch_size = batch_size
+#         for k, v in kwargs.values():
+#             setattr(self, k, v)
+
+#     def __call__(self, ref=None, gen=None, pref=None, pgen=None):
+#         assert (ref is None) != (pref is None), "specify ref xor pref"
+#         assert (gen is None) != (pgen is None), "specify gen xor pgen"
+#         if pref is None:
+#             pref = self.precalc(ref)
+#         if pgen is None:
+#             pgen = self.precalc(gen)
+#         return self.metric(pref, pgen)
+
+#     def precalc(self, moleclues):
+#         raise NotImplementedError
+
+#     def metric(self, pref, pgen):
+#         raise NotImplementedError
+
+
+# class SNNMetric(Metric):
+#     """
+#     Computes average max similarities of gen SMILES to ref SMILES
+#     """
+
+#     def __init__(self, fp_type='morgan', **kwargs):
+#         self.fp_type = fp_type
+#         super().__init__(**kwargs)
+
+#     def precalc(self, mols):
+#         return {'fps': fingerprints(mols, n_jobs=self.n_jobs,
+#                                     fp_type=self.fp_type)}
+
+#     def metric(self, pref, pgen):
+#         return average_agg_tanimoto(pref['fps'], pgen['fps'],
+#                                     device=self.device)
+
+
+# def cos_similarity(ref_counts, gen_counts):
+#     """
+#     Computes cosine similarity between
+#      dictionaries of form {name: count}. Non-present
+#      elements are considered zero:
+
+#      sim = <r, g> / ||r|| / ||g||
+#     """
+#     if len(ref_counts) == 0 or len(gen_counts) == 0:
+#         return np.nan
+#     keys = np.unique(list(ref_counts.keys()) + list(gen_counts.keys()))
+#     ref_vec = np.array([ref_counts.get(k, 0) for k in keys])
+#     gen_vec = np.array([gen_counts.get(k, 0) for k in keys])
+#     return 1 - cos_distance(ref_vec, gen_vec)
+
+
+# class FragMetric(Metric):
+#     def precalc(self, mols):
+#         return {'frag': compute_fragments(mols, n_jobs=self.n_jobs)}
+
+#     def metric(self, pref, pgen):
+#         return cos_similarity(pref['frag'], pgen['frag'])
+
+
+# class ScafMetric(Metric):
+#     def precalc(self, mols):
+#         return {'scaf': compute_scaffolds(mols, n_jobs=self.n_jobs)}
+
+#     def metric(self, pref, pgen):
+#         return cos_similarity(pref['scaf'], pgen['scaf'])
+
+
+# class WassersteinMetric(Metric):
+#     def __init__(self, func=None, **kwargs):
+#         self.func = func
+#         super().__init__(**kwargs)
+
+#     def precalc(self, mols):
+#         if self.func is not None:
+#             values = mapper(self.n_jobs)(self.func, mols)
+#         else:
+#             values = mols
+#         return {'values': values}
+
+#     def metric(self, pref, pgen):
+#         return wasserstein_distance(
+#             pref['values'], pgen['values']
+#         )
+
+
+# def get_frag(gen):
+#     mols = mapper(pool)(get_mol, gen)
+#     kwargs = {'n_jobs': pool, 'device': device, 'batch_size': batch_size}