nerdd-module 0.3.50__tar.gz → 0.3.51__tar.gz

{nerdd_module-0.3.50 → nerdd_module-0.3.51}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nerdd-module
-Version: 0.3.50
+Version: 0.3.51
 Summary: Base package to create NERDD modules
 Author-email: Steffen Hirte <steffen.hirte@univie.ac.at>
 Maintainer-email: Steffen Hirte <steffen.hirte@univie.ac.at>

nerdd_module-0.3.51/nerdd_module/preprocessing/__init__.py

@@ -0,0 +1,81 @@
+"""
+Molecular preprocessing pipeline components.
+
+This package provides a comprehensive set of preprocessing steps for molecular data processing
+pipelines. These steps can be chained together to clean, standardize, and validate molecular
+datasets commonly used in cheminformatics and drug discovery.
+
+The preprocessing steps inherit from the base `PreprocessingStep` class and can be easily combined
+to create custom preprocessing pipelines. Each step operates on molecular records and can transform
+molecules, report problems, or filter out invalid structures.
+
+Available Preprocessing Steps
+-----------------------------
+
+- `CheckValidSmiles` : Validates molecules through SMILES round-trip conversion
+- `Sanitize` : Validates and corrects molecular structures using RDKit sanitization
+- `FilterByWeight` : Filters molecules based on molecular weight thresholds
+- `FilterByElement` : Filters molecules based on allowed elemental composition
+- `StandardizeWithCsp` : Standardizes molecules using ChEMBL Structure Pipeline
+- `GetParentMolWithCsp` : Extracts parent molecules using ChEMBL Structure Pipeline
+- `RemoveHydrogens` : Removes hydrogen atoms from molecular representations
+- `RemoveSmallFragments` : Removes small fragments, keeping only the largest component
+- `RemoveStereochemistry` : Removes stereochemical information from molecules
+
+Base Classes
+------------
+
+- `PreprocessingStep` : Abstract base class for all preprocessing steps
+
+Examples
+--------
+
+Basic usage of individual preprocessing steps:
+
+>>> from nerdd_module.preprocessing import FilterByWeight, RemoveHydrogens, Sanitize
+>>>
+>>> # Create preprocessing steps
+>>> weight_filter = FilterByWeight(min_weight=150, max_weight=500)
+>>> hydrogen_remover = RemoveHydrogens()
+>>> sanitizer = Sanitize()
+
+Creating a complete preprocessing pipeline:
+
+>>> from nerdd_module.preprocessing import (
+...     CheckValidSmiles, FilterByElement, RemoveSmallFragments,
+...     Sanitize, StandardizeWithCsp, ORGANIC_SUBSET
+... )
+>>>
+>>> # Define a comprehensive preprocessing pipeline
+>>> pipeline_steps = [
+...     Sanitize(),                       # Sanitize molecules
+...     CheckValidSmiles(),               # Validate SMILES representation
+...     RemoveSmallFragments(),           # Remove salts and solvents
+...     FilterByElement(ORGANIC_SUBSET),  # Keep only organic molecules
+...     StandardizeWithCsp(),             # Standardize using chembl_structure_pipeline
+... ]
+
+
+Notes
+-----
+* All preprocessing steps follow the same interface defined by `PreprocessingStep`
+* Steps can be chained together to create comprehensive preprocessing pipelines
+* Problems encountered during preprocessing are accumulated in the record's "problems" list
+* Some steps require optional dependencies (e.g., `chembl_structure_pipeline`)
+* The order of preprocessing steps can significantly impact the final results
+
+See Also
+--------
+nerdd_module.steps : Base classes for pipeline steps nerdd_module.problem : Problem reporting
+classes used by preprocessing steps
+"""
+
+from .check_valid_smiles import *
+from .chembl_structure_pipeline import *
+from .filter_by_element import *
+from .filter_by_weight import *
+from .preprocessing_step import *
+from .remove_hydrogens import *
+from .remove_small_fragments import *
+from .remove_stereochemistry import *
+from .sanitize import *

nerdd_module-0.3.51/nerdd_module/preprocessing/check_valid_smiles.py

@@ -0,0 +1,74 @@
+"""
+SMILES validation preprocessing step for molecular data.
+
+This module provides functionality to validate molecular representations by converting them to
+SMILES format and attempting to parse them back. This round-trip validation ensures that molecules
+can be properly serialized and deserialized as SMILES strings.
+"""
+
+from typing import List, Optional, Tuple
+
+from rdkit.Chem import Mol, MolFromSmiles, MolToSmiles
+
+from ..problem import InvalidSmiles, Problem
+from .preprocessing_step import PreprocessingStep
+
+__all__ = ["CheckValidSmiles"]
+
+
+class CheckValidSmiles(PreprocessingStep):
+    """
+    Preprocessing step that validates molecules through SMILES round-trip conversion.
+
+    This class validates molecular representations by converting them to SMILES format and then
+    attempting to parse the SMILES back to a molecule object. This round-trip validation ensures
+    that molecules can be properly represented as SMILES strings, which is an indicator for a valid
+    molecular structure. Molecules that fail the round-trip test are considered invalid and removed.
+
+    Parameters
+    ----------
+    None
+
+    Examples
+    --------
+    >>> # Create a SMILES validation step
+    >>> smiles_check = CheckValidSmiles()
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    def _preprocess(self, mol: Mol) -> Tuple[Optional[Mol], List[Problem]]:
+        """
+        Validate a molecule through SMILES round-trip conversion.
+
+        Converts the input molecule to a canonical SMILES string and then attempts to parse it back
+        to a molecule object. If the round-trip conversion fails, the molecule is considered
+        invalid.
+
+        Parameters
+        ----------
+        mol : Mol
+            RDKit Mol object representing the molecule to be validated.
+
+        Returns
+        -------
+        Tuple[Optional[Mol], List[Problem]]
+            A tuple containing:
+            * The original molecule if SMILES validation succeeded, or None if validation failed
+            * An empty list if validation succeeded, or a list containing an InvalidSmiles problem
+              if validation failed
+
+        Notes
+        -----
+        The validation process converts the molecule to canonical SMILES.
+        """
+        problems = []
+
+        smi = MolToSmiles(mol, True)
+        check_mol = MolFromSmiles(smi)
+        if check_mol is None:
+            problems.append(InvalidSmiles())
+            mol = None
+
+        return mol, problems

nerdd_module-0.3.51/nerdd_module/preprocessing/chembl_structure_pipeline.py

@@ -0,0 +1,183 @@
+"""
+ChEMBL Structure Pipeline preprocessing steps for molecular data.
+
+This module provides preprocessing steps that utilize the ChEMBL Structure Pipeline library for
+molecule standardization and parent molecule extraction.
+"""
+
+import warnings
+from typing import List, Optional, Tuple
+
+from rdkit.Chem import Mol
+
+from ..polyfills import BlockLogs
+from ..problem import Problem
+from .preprocessing_step import PreprocessingStep
+
+# before importing chembl_structure_pipeline, we need to suppress RDKit warnings
+warnings.filterwarnings(
+    "ignore",
+    category=DeprecationWarning,
+    module="rdkit.Chem.MolStandardize",
+)
+
+# We check if chembl_structure_pipeline is installed. Since importing this library already logs
+# messages, we suppress them using RDKit's BlockLogs.
+with BlockLogs():
+    try:
+        from chembl_structure_pipeline import get_parent_mol, standardize_mol
+
+        import_error = None
+    except ImportError as e:
+        # raise ImportError later when using this class
+        # --> this allows to use the rest of the package without chembl_structure_pipeline
+        import_error = e
+
+__all__ = ["GetParentMolWithCsp", "StandardizeWithCsp"]
+
+
+class StandardizeWithCsp(PreprocessingStep):
+    """
+    Preprocessing step that standardizes molecules using ChEMBL Structure Pipeline.
+
+    This class applies the ChEMBL Structure Pipeline standardization procedures to normalize
+    molecular representations. The standardization includes tautomer normalization, charge
+    neutralization, and other structural standardizations commonly used in pharmaceutical databases.
+
+    Parameters
+    ----------
+    None
+
+    Raises
+    ------
+    ImportError
+        If the chembl_structure_pipeline library is not installed.
+
+    Examples
+    --------
+    >>> # Create a standardization step (requires chembl_structure_pipeline)
+    >>> standardize_step = StandardizeWithCsp()
+
+    Notes
+    -----
+    * Requires the chembl_structure_pipeline library to be installed
+    * Automatically removes 3D conformers as the pipeline cannot handle them
+    * Uses ChEMBL's standardize_mol function which applies comprehensive molecular standardization
+      procedures
+    * If standardization fails, the original molecule is returned with a problem
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+
+        if import_error is not None:
+            raise import_error
+
+    def _preprocess(self, mol: Mol) -> Tuple[Optional[Mol], List[Problem]]:
+        """
+        Standardize a molecule using ChEMBL Structure Pipeline.
+
+        Applies ChEMBL's standardization procedures to normalize the molecular representation. The
+        process removes 3D conformers before applying the standardize_mol function.
+
+        Parameters
+        ----------
+        mol : Mol
+            RDKit Mol object representing the molecule to be standardized.
+
+        Returns
+        -------
+        Tuple[Optional[Mol], List[Problem]]
+            A tuple containing:
+            * The standardized molecule if successful, or the original molecule if standardization
+              failed
+            * An empty list if standardization succeeded, or a list containing a Problem instance
+              with code "csp_error" if standardization failed
+        """
+        problems: List[Problem] = []
+
+        # chembl structure pipeline cannot handle molecules with 3D coordinates
+        # --> delete conformers
+        mol.RemoveAllConformers()
+
+        # standardization via chembl structure pipeline
+        preprocessed_mol = standardize_mol(mol)
+
+        if preprocessed_mol is None:
+            problems.append(Problem("csp_error", "Could not standardize the molecule."))
+            preprocessed_mol = mol
+
+        return preprocessed_mol, problems
+
+
+class GetParentMolWithCsp(PreprocessingStep):
+    """
+    Preprocessing step that extracts parent molecules using ChEMBL Structure Pipeline.
+
+    This class uses the ChEMBL Structure Pipeline to identify and extract the parent molecule from
+    complex molecular structures. This process removes salts, solvents, and other fragments while
+    applying ChEMBL's standardization rules.
+
+    Parameters
+    ----------
+    None
+
+    Raises
+    ------
+    ImportError
+        If the chembl_structure_pipeline library is not installed.
+
+    Examples
+    --------
+    >>> # Create a parent molecule extraction step
+    >>> get_parent_step = GetParentMolWithCsp()
+
+    Notes
+    -----
+    * Requires the chembl_structure_pipeline library to be installed
+    * Automatically removes 3D conformers as the pipeline cannot handle them
+    * Applies the get_parent_mol function from the chembl_structure_pipeline library
+    * If parent extraction fails or is flagged for exclusion, the original molecule is returned with
+      a Problem instance
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+
+        if import_error is not None:
+            raise import_error
+
+    def _preprocess(self, mol: Mol) -> Tuple[Optional[Mol], List[Problem]]:
+        """
+        Extract the parent molecule using ChEMBL Structure Pipeline.
+
+        Identifies and returns the main molecular component. The process removes 3D conformers,
+        because chembl_structure_pipeline cannot handle them.
+
+        Parameters
+        ----------
+        mol : Mol
+            RDKit Mol object representing the molecule from which to extract the parent structure.
+
+        Returns
+        -------
+        Tuple[Optional[Mol], List[Problem]]
+            A tuple containing:
+            * The parent molecule if successful, or the original molecule if extraction failed
+            * An empty list if extraction succeeded, or a list containing a Problem instance with
+              code "csp_error" if extraction failed or was flagged for exclusion
+        """
+        problems = []
+
+        # chembl structure pipeline cannot handle molecules with 3D coordinates
+        # --> delete conformers
+        mol.RemoveAllConformers()
+
+        # get parent molecule via chembl structure pipeline
+        preprocessed_mol, exclude_flag = get_parent_mol(mol)
+        if exclude_flag or preprocessed_mol is None:
+            problems.append(Problem("csp_error", "Could not remove small fragments."))
+        if preprocessed_mol is None:
+            preprocessed_mol = mol
+
+        return preprocessed_mol, problems

nerdd_module-0.3.51/nerdd_module/preprocessing/filter_by_element.py

@@ -0,0 +1,148 @@
+"""
+Element filtering preprocessing step for molecular data.
+
+This module provides functionality to filter molecules based on their elemental composition,
+allowing only molecules containing specified allowed elements to pass through the processing
+pipeline.
+"""
+
+from typing import Iterable, List, Optional, Set, Tuple
+
+from rdkit.Chem import Mol
+
+from ..problem import InvalidElementsProblem, Problem
+from .preprocessing_step import PreprocessingStep
+
+__all__ = ["FilterByElement", "ORGANIC_SUBSET"]
+
+ORGANIC_SUBSET = [
+    "H",
+    "B",
+    "C",
+    "N",
+    "O",
+    "F",
+    "Si",
+    "P",
+    "S",
+    "Cl",
+    "Se",
+    "Br",
+    "I",
+]
+"""
+List[str] : Predefined set of elements commonly found in organic molecules.
+
+This list contains the atomic symbols of elements that are typically present in organic and
+drug-like molecules. It can be used as a convenient preset for the FilterByElement class to restrict
+molecules to organic chemistry space.
+
+The elements included are:
+* H (Hydrogen)
+* B (Boron)
+* C (Carbon)
+* N (Nitrogen)
+* O (Oxygen)
+* F (Fluorine)
+* Si (Silicon)
+* P (Phosphorus)
+* S (Sulfur)
+* Cl (Chlorine)
+* Se (Selenium)
+* Br (Bromine)
+* I (Iodine)
+
+Examples
+--------
+>>> filter_step = FilterByElement(ORGANIC_SUBSET)
+>>> # This will only allow molecules containing organic elements
+"""
+
+
+class FilterByElement(PreprocessingStep):
+    """
+    Preprocessing step that filters molecules based on elemental composition.
+
+    This class validates molecules against a specified set of allowed elements. Molecules containing
+    elements not in the allowed set are flagged with a problem instance "invalid_element" and
+    optionally removed from the pipeline.
+
+    Parameters
+    ----------
+    allowed_elements : Iterable[str]
+        An iterable of atomic symbols (element names) that are allowed in molecules. Element symbols
+        are case-insensitive but will be normalized to proper case (first letter uppercase, rest
+        lowercase).
+    remove_invalid_molecules : bool, optional
+        If True, molecules containing disallowed elements are set to None (removed). If False,
+        invalid molecules are kept. Default is False.
+
+    Examples
+    --------
+    >>> # Allow only carbon, nitrogen, oxygen, and hydrogen
+    >>> filter_step = FilterByElement(['C', 'N', 'O', 'H'])
+
+    >>> # Use predefined organic subset, removing invalid molecules
+    >>> filter_step = FilterByElement(ORGANIC_SUBSET, remove_invalid_molecules=True)
+
+    Notes
+    -----
+    * Element symbols are normalized to proper case (e.g., 'cl' becomes 'Cl')
+    * Even if remove_invalid_molecules is set to False, molecules with invalid elements are still
+      marked with a problem instance
+    * Hydrogen atoms are handled specially since they may not be explicit in the molecular
+      representation and are detected via GetTotalNumHs()
+    """
+
+    def __init__(
+        self, allowed_elements: Iterable[str], remove_invalid_molecules: bool = False
+    ) -> None:
+        super().__init__()
+        self._allowed_elements = {a[0].upper() + a[1:] for a in allowed_elements}
+        self._hydrogen_in_allowed_elements = "H" in self._allowed_elements
+        self._remove_invalid_molecules = remove_invalid_molecules
+
+    def _preprocess(self, mol: Mol) -> Tuple[Optional[Mol], List[Problem]]:
+        """
+        Filter a molecule by comparing its elemental composition against allowed elements.
+
+        Parameters
+        ----------
+        mol : Mol
+            RDKit Mol object representing the molecule to be validated.
+
+        Returns
+        -------
+        Tuple[Optional[Mol], List[Problem]]
+            A tuple containing:
+            * The original molecule if all elements are allowed, or None if disallowed elements are
+              found and remove_invalid_molecules is True
+            * A list containing an InvalidElementsProblem if disallowed elements are found,
+              otherwise an empty list
+
+        Notes
+        -----
+        Hydrogen detection is special-cased because hydrogen atoms are often implicit in molecular
+        representations and detected via atom.GetTotalNumHs().
+        """
+        problems = []
+        result_mol = mol
+
+        elements: Set[str] = {atom.GetSymbol() for atom in mol.GetAtoms()}
+        invalid_elements = elements - self._allowed_elements
+
+        # special case: hydrogens are not recognized by mol.GetAtoms()
+        if not self._hydrogen_in_allowed_elements:
+            # get the number of hydrogens in mol
+            for a in mol.GetAtoms():
+                if a.GetTotalNumHs() > 0:
+                    invalid_elements.add("H")
+                    break
+
+        if len(invalid_elements) > 0:
+            if self._remove_invalid_molecules:
+                result_mol = None
+
+            problems.append(InvalidElementsProblem(invalid_elements))
+
+        return result_mol, problems

nerdd_module-0.3.51/nerdd_module/preprocessing/filter_by_weight.py

@@ -0,0 +1,95 @@
+"""
+Molecular weight filtering preprocessing step.
+
+This module provides a preprocessing step that filters molecules based on their molecular weight.
+This is desirable for models having a runtime scaling with molecule size.
+"""
+
+from typing import List, Optional, Tuple
+
+from rdkit.Chem import Mol
+from rdkit.Chem.rdMolDescriptors import CalcExactMolWt
+
+from ..problem import InvalidWeightProblem, Problem
+from .preprocessing_step import PreprocessingStep
+
+__all__ = ["FilterByWeight"]
+
+
+class FilterByWeight(PreprocessingStep):
+    """
+    Preprocessing step that filters molecules based on molecular weight.
+
+    This class validates molecules against specified minimum and maximum molecular weight
+    thresholds. Molecules outside these bounds are flagged and optionally removed from the pipeline.
+
+    Parameters
+    ----------
+    min_weight : float, optional
+        Minimum allowed molecular weight in Daltons (Da). Default is 0.
+    max_weight : float, optional
+        Maximum allowed molecular weight in Daltons (Da). Default is infinity.
+    remove_invalid_molecules : bool, optional
+        If True, molecules outside the weight range are set to None (removed). If False, invalid
+        molecules are kept. Default is False.
+
+    Examples
+    --------
+    >>> # Filter molecules between 150 and 500 Da, keeping invalid ones
+    >>> filter_step = FilterByWeight(min_weight=150, max_weight=500)
+
+    >>> # Filter molecules below 1000 Da, removing invalid ones
+    >>> filter_step = FilterByWeight(max_weight=1000, remove_invalid_molecules=True)
+
+    >>> # Only set minimum weight threshold
+    >>> filter_step = FilterByWeight(min_weight=100)
+
+    Notes
+    -----
+    * Even if remove_invalid_molecules is set to False, molecules with invalid weight are still
+      marked with a problem instance
+    * The molecular weight is calculated using RDKit's CalcExactMolWt function
+    """
+
+    def __init__(
+        self,
+        min_weight: float = 0,
+        max_weight: float = float("inf"),
+        remove_invalid_molecules: bool = False,
+    ) -> None:
+        super().__init__()
+        self._min_weight = min_weight
+        self._max_weight = max_weight
+        self._remove_invalid_molecules = remove_invalid_molecules
+
+    def _preprocess(self, mol: Mol) -> Tuple[Optional[Mol], List[Problem]]:
+        """
+        Filter a molecule based on its molecular weight.
+
+        Calculates the exact molecular weight of the input molecule and validates it against the
+        configured minimum and maximum weight thresholds.
+
+        Parameters
+        ----------
+        mol : Mol
+            RDKit Mol object representing the molecule to be validated.
+
+        Returns
+        -------
+        Tuple[Optional[Mol], List[Problem]]
+            A tuple containing:
+            * The original molecule if within weight bounds, or None if outside bounds and
+              remove_invalid_molecules is True
+            * A list containing an InvalidWeightProblem if the molecule is outside the weight
+              bounds, otherwise an empty list
+        """
+        problems = []
+        result_mol = mol
+
+        weight = CalcExactMolWt(mol)
+        if weight < self._min_weight or weight > self._max_weight:
+            if self._remove_invalid_molecules:
+                result_mol = None
+            problems.append(InvalidWeightProblem(weight, self._min_weight, self._max_weight))
+
+        return result_mol, problems