nerdd-module 0.3.3__tar.gz → 0.3.24__tar.gz

nerdd_module-0.3.24/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.2
+Name: nerdd-module
+Version: 0.3.24
+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>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2023 - present, The Computational Drug Discovery and Design Group (COMP3D)
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+Project-URL: Repository, https://github.com/molinfo-vienna/nerdd-module
+Keywords: science,research,development,nerdd
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development
+Classifier: Topic :: Scientific/Engineering
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.2.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: filetype~=1.2.0
+Requires-Dist: rich-click>=1.7.1
+Requires-Dist: stringcase>=1.2.0
+Requires-Dist: decorator>=5.1.1
+Requires-Dist: pydantic>=2
+Requires-Dist: importlib-resources>=5; python_version < "3.9"
+Requires-Dist: importlib-metadata>=4.6; python_version < "3.10"
+Requires-Dist: typing_extensions>=4.0.1; python_version < "3.8"
+Provides-Extra: dev
+Requires-Dist: mypy>=1; extra == "dev"
+Requires-Dist: ruff==0.7.1; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Requires-Dist: rdkit-stubs; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-decorator; extra == "dev"
+Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: pre-commit>=2; extra == "dev"
+Provides-Extra: rdkit
+Requires-Dist: rdkit>=2022.3.3; extra == "rdkit"
+Provides-Extra: csp
+Requires-Dist: chembl_structure_pipeline>=1.0.0; extra == "csp"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-sugar; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-bdd<8; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Requires-Dist: pytest-watcher; extra == "test"
+Requires-Dist: hypothesis; extra == "test"
+Requires-Dist: hypothesis-rdkit; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings; extra == "docs"
+
+# NERDD Module
+
+This package provides the basis to implement molecular prediction modules in the
+NERDD ecosystem.
+
+## Installation
+
+``` bash
+pip install -U nerdd-module
+```
+
+
+## Contribute
+
+1. Fork and clone the code
+2. Install test dependencies with `pip install -e .[test,dev,csp]` 
+3. Install pre-commit hooks `pre-commit install`
+4. Run tests via `pytest` or `pytest-watch` (short: `ptw`)
+5. Build docs via `pip install -e .[docs]`  and `mkdocs serve` 

nerdd_module-0.3.24/README.md

@@ -0,0 +1,19 @@
+# NERDD Module
+
+This package provides the basis to implement molecular prediction modules in the
+NERDD ecosystem.
+
+## Installation
+
+``` bash
+pip install -U nerdd-module
+```
+
+
+## Contribute
+
+1. Fork and clone the code
+2. Install test dependencies with `pip install -e .[test,dev,csp]` 
+3. Install pre-commit hooks `pre-commit install`
+4. Run tests via `pytest` or `pytest-watch` (short: `ptw`)
+5. Build docs via `pip install -e .[docs]`  and `mkdocs serve` 

{nerdd_module-0.3.3 → nerdd_module-0.3.24}/nerdd_module/__init__.py

@@ -1,7 +1,7 @@
 from .cli import *
-from .input import ReaderRegistry
+from .converters import *
 from .model import *
-from .output import WriterRegistry
+from .output import *
 from .polyfills import get_entry_points
 from .problem import *
 from .version import *

{nerdd_module-0.3.3 → nerdd_module-0.3.24}/nerdd_module/cli.py

@@ -1,16 +1,22 @@
 import logging
 import os
 import sys
+from typing import Any, Callable
 
 import rich_click as click
 from decorator import decorator
-from stringcase import spinalcase  # type: ignore
+from stringcase import spinalcase
+
+from .config import JobParameter
+from .input import Reader
+from .model import Model
+from .output import FileWriter, Writer
 
 __all__ = ["auto_cli"]
 
 input_description = """{description}
 
-INPUT molecules are provided as file paths or strings. The following formats are 
+INPUT molecules are provided as file paths or strings. The following formats are
 supported:
 
 {input_format_list}
@@ -19,46 +25,60 @@ Note that input formats shouldn't be mixed.
 """
 
 
-def infer_click_type(param):
-    if "choices" in param:
-        choices = [c["value"] for c in param["choices"]]
+def infer_click_type(param: JobParameter) -> click.ParamType:
+    if param.choices is not None:
+        choices = [c.value for c in param.choices]
         return click.Choice(choices)
 
     type_map = {
-        "float": float,
-        "int": int,
-        "str": str,
-        "bool": bool,
+        "float": click.FLOAT,
+        "integer": click.INT,
+        "string": click.STRING,
+        "bool": click.BOOL,
     }
 
-    return type_map[param.get("type")]
+    t = param.type
+    if t not in type_map:
+        raise ValueError(f"Unknown type {t} for parameter {param.name}")
+
+    return type_map[t]
 
 
 @decorator
-def auto_cli(f, *args, **kwargs):
+def auto_cli(f: Callable[..., Model], *args: Any, **kwargs: Any) -> None:
     # infer the command name
     command_name = os.path.basename(sys.argv[0])
 
     # get the model
     model = f()
 
-    config = model.get_config()
-
     # compose cli description
-    description = config.get("description", "")
-
     input_format_list = "\n".join([f"* {fmt}" for fmt in ["smiles", "sdf", "inchi"]])
 
     help_text = input_description.format(
-        description=description, input_format_list=input_format_list
+        description=model.description, input_format_list=input_format_list
     )
 
-    output_format_list = ["sdf", "csv"]
+    output_format_list = [
+        output_format
+        for output_format, writer in Writer.get_writers(output_file=None).items()
+        if isinstance(writer, FileWriter)
+    ]
 
     # compose footer with examples
     examples = []
-    if "example_smiles" in config:
-        examples.append(config["example_smiles"])
+    if hasattr(model, "get_config"):
+        example_smiles = model.get_config().example_smiles
+        if example_smiles is not None:
+            examples.append(example_smiles)
+
+    for ReaderClass in Reader.get_reader_mapping():
+        if hasattr(ReaderClass, "config"):
+            reader_examples = ReaderClass.config.get("examples", [])
+            for example in reader_examples:
+                # check if example fits on one line
+                if len(example) < 120 and "\n" not in example:
+                    examples.append(example)
 
     if len(examples) > 0:
         footer = "Examples:\n"
@@ -67,26 +87,16 @@ def auto_cli(f, *args, **kwargs):
     else:
         footer = ""
 
-    # show_default=True: default values are shown in the help text
-    # show_metavars_column=False: the column types are not in a separate column
-    # append_metavars_help=True: the column types are shown below the help text
-    @click.command(context_settings={"show_default": True}, help=help_text)
-    @click.rich_config(
-        help_config=click.RichHelpConfiguration(
-            use_markdown=True,
-            show_metavars_column=False,
-            append_metavars_help=True,
-            footer_text=footer,
-        )
-    )
-    @click.argument("input", type=click.Path(), nargs=-1, required=True)
+    #
+    # Define the CLI entry point
+    #
     def main(
-        input,
+        input: Any,
         format: str,
         output: click.Path,
         log_level: str,
-        **kwargs,
-    ):
+        **kwargs: Any,
+    ) -> None:
         logging.basicConfig(level=log_level.upper())
 
         # write results
@@ -99,17 +109,22 @@ def auto_cli(f, *args, **kwargs):
 
         model.predict(input, output_format=format, output_file=output_handle, **kwargs)
 
+    #
+    # Add required input parameter
+    #
+    main = click.argument("input", type=click.Path(), nargs=-1, required=True)(main)
+
     #
     # Add job parameters
     #
-    for param in config.get("job_parameters", []):
+    for param in model.job_parameters:
         # convert parameter name to spinal case (e.g. "max_confs" -> "max-confs")
-        param_name = spinalcase(param["name"])
+        param_name = spinalcase(param.name)
         main = click.option(
             f"--{param_name}",
-            default=param.get("default", None),
+            default=param.default,
             type=infer_click_type(param),
-            help=param.get("help_text", None),
+            help=param.help_text,
         )(main)
 
     #
@@ -132,10 +147,26 @@ def auto_cli(f, *args, **kwargs):
     main = click.option(
         "--log-level",
         default="warning",
-        type=click.Choice(
-            ["debug", "info", "warning", "error", "critical"], case_sensitive=False
-        ),
+        type=click.Choice(["debug", "info", "warning", "error", "critical"], case_sensitive=False),
         help="The logging level.",
     )(main)
 
-    return main()
+    #
+    # Create Rich command
+    #
+
+    # show_metavars_column=False: the column types are not in a separate column
+    # append_metavars_help=True: the column types are shown below the help text
+    main = click.rich_config(
+        help_config=click.RichHelpConfiguration(
+            use_markdown=True,
+            show_metavars_column=False,
+            append_metavars_help=True,
+            footer_text=footer,
+        )
+    )(main)
+
+    # show_default=True: default values are shown in the help text
+    main = click.command(context_settings={"show_default": True}, help=help_text)(main)
+
+    main()

{nerdd_module-0.3.3 → nerdd_module-0.3.24}/nerdd_module/config/__init__.py

@@ -2,6 +2,7 @@ from .configuration import *
 from .default_configuration import *
 from .dict_configuration import *
 from .merged_configuration import *
+from .models import *
 from .package_configuration import *
 from .search_yaml_configuration import *
 from .yaml_configuration import *

nerdd_module-0.3.24/nerdd_module/config/configuration.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from .models import Module
+
+__all__ = ["Configuration"]
+
+
+class Configuration(ABC):
+    def __init__(self) -> None:
+        self._cached_config: Optional[Module] = None
+
+    def get_dict(self) -> Module:
+        if self._cached_config is None:
+            config = self._get_dict()
+
+            # validate the config
+            module = Module(**config)
+
+            self._cached_config = module
+
+        return self._cached_config
+
+    @abstractmethod
+    def _get_dict(self) -> dict:
+        pass
+
+    def is_empty(self) -> bool:
+        return self.get_dict() == {}
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self._get_dict()})"

{nerdd_module-0.3.3 → nerdd_module-0.3.24}/nerdd_module/config/default_configuration.py

@@ -1,3 +1,5 @@
+from typing import Any
+
 from stringcase import snakecase  # type: ignore
 
 from ..polyfills import version
@@ -7,7 +9,7 @@ __all__ = ["DefaultConfiguration"]
 
 
 class DefaultConfiguration(DictConfiguration):
-    def __init__(self, nerdd_module):
+    def __init__(self, nerdd_module: Any) -> None:
         # generate a name from the module name
         class_name = nerdd_module.__class__.__name__
         if class_name.endswith("Model"):

{nerdd_module-0.3.3 → nerdd_module-0.3.24}/nerdd_module/config/merged_configuration.py

@@ -6,7 +6,7 @@ from .dict_configuration import DictConfiguration
 __all__ = ["MergedConfiguration"]
 
 
-def merge(*args):
+def merge(*args: dict) -> dict:
     assert len(args) > 0
 
     first_entry = args[0]
@@ -41,4 +41,4 @@ def merge(*args):
 
 class MergedConfiguration(DictConfiguration):
     def __init__(self, *configs: Configuration):
-        super().__init__(merge(*[c.get_dict() for c in configs]))
+        super().__init__(merge(*[c._get_dict() for c in configs]))

nerdd_module-0.3.24/nerdd_module/config/models.py

@@ -0,0 +1,199 @@
+from typing import Any, List, Optional, Union
+
+from pydantic import BaseModel, computed_field, model_validator
+from stringcase import spinalcase
+
+from ..polyfills import Literal
+
+
+class Partner(BaseModel):
+    name: str
+    logo: str
+    url: Optional[str] = None
+
+
+class Author(BaseModel):
+    """
+    Author information
+
+    Attributes:
+        first_name : str
+            First name of the author.
+        last_name : str
+            Last name of the author.
+        email : Optional[str]
+            Email of the author. If provided, the author is a corresponding author.
+    """
+
+    first_name: str
+    last_name: str
+    email: Optional[str] = None
+
+
+class Publication(BaseModel):
+    title: str
+    authors: List[Author] = []
+    journal: str
+    year: int
+    doi: Optional[str]
+
+
+class JobParameterChoice(BaseModel):
+    value: str
+    label: Optional[str] = None
+
+
+class JobParameter(BaseModel):
+    name: str
+    type: str
+    visible_name: Optional[str] = None
+    help_text: Optional[str] = None
+    default: Any = None
+    required: bool = False
+    choices: Optional[List[JobParameterChoice]] = None
+
+
+Task = Literal[
+    "molecular_property_prediction",
+    "atom_property_prediction",
+    "derivative_property_prediction",
+]
+Level = Literal["molecule", "atom", "derivative"]
+
+FormatSpec = Union[List[str], str]
+
+
+class IncludeExcludeFormatSpec(BaseModel):
+    include: Optional[FormatSpec]
+    exclude: Optional[FormatSpec]
+
+
+class ResultProperty(BaseModel):
+    name: str
+    type: str
+    visible_name: Optional[str] = None
+    visible: bool = True
+    help_text: Optional[str] = None
+    sortable: bool = False
+    group: Optional[str] = None
+    level: Level = "molecule"
+    formats: Union[FormatSpec, IncludeExcludeFormatSpec, None] = None
+    representation: Optional[str] = None
+    from_property: Optional[str] = None
+    image_width: Optional[int] = None
+    image_height: Optional[int] = None
+
+    def is_visible(self, output_format: str) -> bool:
+        formats = self.formats
+
+        if formats is None:
+            return True
+        elif isinstance(formats, list):
+            return output_format in formats
+        elif isinstance(formats, IncludeExcludeFormatSpec):
+            include = formats.include
+            exclude = formats.exclude or []
+            return (include is None or output_format in include) and output_format not in exclude
+        else:
+            raise ValueError(f"Invalid formats declaration {formats} in result property {self}")
+
+
+class Module(BaseModel):
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def id(self) -> str:
+        # TODO: incorporate versioning
+        # compute the primary key from name and version
+        # if "version" in module.keys():
+        #     version = module["version"]
+        # else:
+        #     version = "1.0.0"
+        # name = module["name"]
+
+        return spinalcase(self.name)
+
+    task: Optional[Task] = None
+    rank: Optional[int] = None
+    name: str
+    batch_size: int = 100
+    version: Optional[str] = None
+    visible_name: Optional[str] = None
+    visible: bool = True
+    logo: Optional[str] = None
+    logo_title: Optional[str] = None
+    logo_caption: Optional[str] = None
+    example_smiles: Optional[str] = None
+    title: Optional[str] = None
+    description: Optional[str] = None
+    partners: List[Partner] = []
+    publications: List[Publication] = []
+    about: Optional[str] = None
+    job_parameters: List[JobParameter] = []
+    result_properties: List[ResultProperty] = []
+
+    def get_property_columns_of_type(self, t: Level) -> List[ResultProperty]:
+        return [c for c in self.result_properties if c.level == t]
+
+    def molecular_property_columns(self) -> List[ResultProperty]:
+        return self.get_property_columns_of_type("molecule")
+
+    def atom_property_columns(self) -> List[ResultProperty]:
+        return self.get_property_columns_of_type("atom")
+
+    def derivative_property_columns(self) -> List[ResultProperty]:
+        return self.get_property_columns_of_type("derivative")
+
+    def get_visible_properties(self, output_format: str) -> List[ResultProperty]:
+        return [p for p in self.result_properties if p.is_visible(output_format)]
+
+    @model_validator(mode="after")
+    @classmethod
+    def validate_model(cls, values: Any) -> Any:
+        assert isinstance(values, Module)
+
+        num_atom_properties = len(values.get_property_columns_of_type("atom"))
+        num_derivative_properties = len(values.get_property_columns_of_type("derivative"))
+        task = values.task
+        if task is None:
+            # if task is not specified, try to derive it from the result_properties
+            if num_atom_properties > 0:
+                task = "atom_property_prediction"
+            elif num_derivative_properties > 0:
+                task = "derivative_property_prediction"
+            else:
+                task = "molecular_property_prediction"
+
+            values.task = task
+        else:
+            # if task is specified, check if it is consistent with the result_properties
+            if num_atom_properties > 0:
+                assert (
+                    task == "atom_property_prediction"
+                ), "Task should be atom_property_prediction if atom properties are present."
+            elif num_derivative_properties > 0:
+                assert task == "derivative_property_prediction", (
+                    "Task should be derivative_property_prediction if derivative properties "
+                    "are present."
+                )
+            else:
+                assert task == "molecular_property_prediction", (
+                    "Task should be molecular_property_prediction if no atom or derivative "
+                    "properties are present."
+                )
+
+        # check that a module can only predict atom or derivative properties, not both
+        assert (
+            num_atom_properties == 0 or num_derivative_properties == 0
+        ), "A module can only predict atom or derivative properties, not both."
+
+        # check that two properties with the same group appear next to each other
+        groups = [p.group for p in values.result_properties if p.group is not None]
+        for group in groups:
+            indices = [i for i, p in enumerate(values.result_properties) if p.group == group]
+            for i, j in zip(indices[:-1], indices[1:]):
+                assert i + 1 == j, (
+                    f"Properties with the same group should appear next to each other, "
+                    f"but group {group} appears at incides {i} and {j}."
+                )
+
+        return values

nerdd_module-0.3.24/nerdd_module/config/package_configuration.py

@@ -0,0 +1,37 @@
+import logging
+
+from ..polyfills import files
+from .configuration import Configuration
+from .dict_configuration import DictConfiguration
+from .yaml_configuration import YamlConfiguration
+
+__all__ = ["PackageConfiguration"]
+
+logger = logging.getLogger(__name__)
+
+
+class PackageConfiguration(Configuration):
+    def __init__(self, package: str, filename: str = "nerdd.yml") -> None:
+        super().__init__()
+
+        package_path = package.split(".")
+        package_root = package_path[0]
+        remaining_path = package_path[1:]
+
+        # get the resource directory
+        root_dir = files(package_root)
+        assert root_dir is not None
+
+        self.config: Configuration = DictConfiguration({})
+
+        # navigate to the config file
+        config_file = root_dir.joinpath(*remaining_path, filename)
+        assert config_file is not None and config_file.is_file()
+
+        logger.info(f"Found configuration file in package: {config_file}")
+        self.config = YamlConfiguration(
+            config_file.open(), base_path=root_dir.joinpath(*remaining_path)
+        )
+
+    def _get_dict(self) -> dict:
+        return self.config._get_dict()

{nerdd_module-0.3.3 → nerdd_module-0.3.24}/nerdd_module/config/search_yaml_configuration.py

@@ -1,7 +1,6 @@
 import logging
 import os
-import sys
-from typing import Any, Optional
+from typing import Optional
 
 from .configuration import Configuration
 from .dict_configuration import DictConfiguration
@@ -13,7 +12,9 @@ logger = logging.getLogger(__name__)
 
 
 class SearchYamlConfiguration(DictConfiguration):
-    def __init__(self, start: str, base_path: Optional[str] = None) -> None:
+    def __init__(
+        self, start: str, base_path: Optional[str] = None, filename: str = "nerdd.yml"
+    ) -> None:
         # provide a default configuration if no configuration file is found
         config: Configuration = DictConfiguration({})
 
@@ -23,8 +24,8 @@ class SearchYamlConfiguration(DictConfiguration):
             # reached)
             leaf = start
             while True:
-                if os.path.isfile(os.path.join(leaf, "nerdd.yml")):
-                    default_config_file = os.path.join(leaf, "nerdd.yml")
+                if os.path.isfile(os.path.join(leaf, filename)):
+                    default_config_file = os.path.join(leaf, filename)
                     break
                 elif leaf == os.path.dirname(leaf):  # reached root
                     default_config_file = None
@@ -32,9 +33,7 @@ class SearchYamlConfiguration(DictConfiguration):
                 leaf = os.path.dirname(leaf)
 
             if default_config_file is not None:
-                logger.info(
-                    f"Found configuration file in project directory: {default_config_file}"
-                )
+                logger.info(f"Found configuration file in project directory: {default_config_file}")
                 config = YamlConfiguration(default_config_file, base_path)
 
-        super().__init__(config.get_dict())
+        super().__init__(config._get_dict())