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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nerdd-module
-Version: 0.3.50
+Version: 0.3.52
 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.50 → nerdd_module-0.3.52}/nerdd_module/config/models.py

@@ -1,3 +1,5 @@
+"""Pydantic models describing module metadata, schema, and parameters."""
+
 from typing import Any, List, Optional, Union
 
 from pydantic import BaseModel, computed_field, model_validator
@@ -7,6 +9,8 @@ from ..polyfills import Literal
 
 
 class Partner(BaseModel):
+    """Partner organization metadata for module marketing/attribution."""
+
     name: str
     logo: str
     url: Optional[str] = None
@@ -31,14 +35,18 @@ class Author(BaseModel):
 
 
 class Publication(BaseModel):
-    title: str
-    authors: List[Author] = []
-    journal: str
-    year: int
+    """Reference to a publication related to the module or model."""
+
+    title: Optional[str] = None
+    authors: Optional[List[Author]] = None
+    journal: Optional[str] = None
+    year: Optional[int] = None
     doi: Optional[str]
 
 
 class ColorPalette(BaseModel):
+    """Optional color mapping for visualizing categorical or numeric outputs."""
+
     type: Optional[str] = None
     name: Optional[str] = None
     domain: Optional[Union[List[str], List[float], List[int], List[bool]]] = None
@@ -47,6 +55,8 @@ class ColorPalette(BaseModel):
 
 
 class Choice(BaseModel):
+    """Select options for job parameters or categorical result properties."""
+
     value: Union[str, int, float, bool]
     label: Optional[str] = None
 
@@ -55,6 +65,8 @@ JobType = Literal["int", "integer", "float", "bool", "boolean", "str", "string"]
 
 
 class JobParameter(BaseModel):
+    """Definition of a user-configurable parameter for a job run."""
+
     name: str
     type: JobType
     visible_name: Optional[str] = None
@@ -64,6 +76,7 @@ class JobParameter(BaseModel):
     choices: Optional[List[Choice]] = None
 
     def validate_value(self, value: Any) -> None:
+        """Validate a provided value against type and choices."""
         if self.type == ["int", "integer"]:
             if not isinstance(value, int):
                 raise ValueError(
@@ -107,11 +120,15 @@ FormatSpec = Union[List[str], str]
 
 
 class IncludeExcludeFormatSpec(BaseModel):
+    """Visibility filter for result properties per output format."""
+
     include: Optional[FormatSpec]
     exclude: Optional[FormatSpec]
 
 
 class ResultProperty(BaseModel):
+    """Schema entry for a model output property."""
+
     name: str
     type: str
     visible_name: Optional[str] = None
@@ -129,6 +146,7 @@ class ResultProperty(BaseModel):
     color_palette: Optional[ColorPalette] = None
 
     def is_visible(self, output_format: str) -> bool:
+        """Return True if property should be shown for the given format."""
         formats = self.formats
 
         if formats is None:
@@ -144,6 +162,8 @@ class ResultProperty(BaseModel):
 
 
 class Module(BaseModel):
+    """Full module configuration: metadata, schema, parameters, and validation."""
+
     @computed_field  # type: ignore[prop-decorator]
     @property
     def id(self) -> str:
@@ -194,6 +214,7 @@ class Module(BaseModel):
     @model_validator(mode="after")
     @classmethod
     def validate_model(cls, values: Any) -> Any:
+        """Enforce consistency between task type and declared result properties."""
         assert isinstance(values, Module)
 
         num_atom_properties = len(values.get_property_columns_of_type("atom"))
@@ -244,10 +265,7 @@ class Module(BaseModel):
         return values
 
     def validate_job_parameters(self, params: dict) -> None:
-        """
-        Validate the job parameters against the module's job parameters.
-        Raises an error if a parameter is missing or has an invalid type.
-        """
+        """Validate provided job parameters against the module declaration."""
         # make sure that all job parameters are present
         for param in self.job_parameters:
             if param.name not in params and param.required:

nerdd_module-0.3.52/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.52/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.52/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.52/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