polyscript-pypi 0.1.0__py3-none-any.whl

polyscript/brics/BRICS_utils.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import pandas as pd
+from polyscript.brics.BRICSMod import BRICSBuild, BRICSDecompose
+from polyscript.utils.logger import INFO, PolyLogger
+from rdkit import Chem
+
+
+def read_df(df_path: str, column_name: str):
+    """Read a column of data from a CSV file.
+
+    Args:
+        df_path: Path to a CSV file.
+        column_name: Name of the column to extract.
+
+    Returns:
+        numpy.ndarray: Values from the specified column.
+
+    Raises:
+        ValueError: If the file is not a CSV or the column is missing.
+    """
+    if not df_path.split(".")[-1] == "csv":
+        raise ValueError("The given file path is not targeting a csv fil")
+    df = pd.read_csv(df_path)
+    if not column_name in df.columns:
+        raise ValueError("The given column is not in the df !")
+    data = df[column_name].values
+    return data
+
+
+def write_data(data, file_path: str, new_line: bool = True):
+    """Write data to a text file.
+
+    Args:
+        data: A list of strings (written one per line) or a single
+            string (written as-is).
+        file_path: Destination file path.
+        new_line: If True (default) and *data* is a list, write each
+            element followed by a newline.  Ignored for non-list data.
+
+    Returns:
+        bool: ``True`` on success.
+    """
+    with open(file_path, "w+") as f:
+        if type(data) == list:
+            if new_line:
+                for d in data:
+                    f.write(d + "\n")
+            else:
+                f.write(str(data))
+        else:
+            f.write(data)
+    return True
+
+
+def apply_BRICS(
+    data: list[str],
+    max_depth: int = 1,
+    output_dir: Optional[str] = None,
+    fmt: str = "csv",
+    is_decomposed: bool = False,
+    log_level: int | str = 2,
+    logger: Optional[PolyLogger] = None,
+) -> Optional[list[dict]]:
+    """Decompose and rebuild molecules via BRICS.
+
+    Parameters
+    ----------
+    data : list[str]
+        SMILES strings to process.  May be full molecules (the default)
+        or already-decomposed BRICS fragments when *is_decomposed* is
+        ``True``.
+    max_depth : int
+        Maximum BRICS build depth (default 1).
+    output_dir : str, optional
+        Directory to save output files to.  When provided, two files are
+        written: ``decomposed_unique.txt`` (fragments, one per line) and
+        ``brics_results.{csv,parquet}`` (table with ``product_smiles`` and
+        ``recipe`` columns).  When ``None`` (default), no files are written
+        and the results are returned as a list of dicts instead.
+    fmt : str
+        Output table format: ``"csv"`` (default) or ``"parquet"``.
+        Ignored when *output_dir* is ``None``.
+    is_decomposed : bool
+        When ``False`` (default), *data* contains full molecules that will
+        be decomposed into BRICS fragments before building.  When ``True``,
+        *data* already contains BRICS fragments (with wildcards like
+        ``[15*]C1CCCCC1``) — the decomposition step is skipped and the
+        fragments go directly to ``BRICSBuild``.
+    log_level : int or str
+        Verbosity threshold used when *logger* is not provided.
+        As an **int**: ``0`` = silent, ``1`` = warnings,
+        ``2`` = info (default), ``3`` = debug.
+        As a **str**: ``"SILENT"``, ``"WARNING"``, ``"INFO"``, ``"DEBUG"``.
+    logger : PolyLogger, optional
+        A pre-configured ``PolyLogger`` instance.  When given, its
+        existing level and handlers are used as-is; *log_level* is
+        ignored.  When ``None``, a console logger at *log_level* is
+        created automatically.
+
+    Returns
+    -------
+    list[dict] or None
+        When *output_dir* is ``None``, returns a list of dicts keyed by
+        ``"product_smiles"``, ``"recipe"``, and ``"mol"``.  When
+        *output_dir* is given, returns ``None`` (results are written to
+        disk instead).
+    """
+    if logger is None:
+        logger = PolyLogger(name="brics", level=log_level)
+        logger.add_console(level=log_level)
+
+    # ── 1. Decompose (skip if already decomposed) ───────────────────────
+    if is_decomposed:
+        # Input is already BRICS fragments — use directly, deduplicate
+        uniques = list(set(data))
+        logger.info(
+            "Using %d pre-decomposed fragments (skipping decomposition)",
+            len(uniques),
+        )
+    else:
+        Decompositions = []
+        for smiles in data:
+            mol = Chem.MolFromSmiles(smiles)
+            if mol is None:
+                logger.warning(f"Invalid SMILES >> {smiles}")
+            if mol is not None:
+                res = BRICSDecompose(mol)
+                Decompositions += res
+
+        uniques = list(set(Decompositions))
+        logger.info("Unique blocks found -> %d", len(uniques))
+
+    # ── 2. Build ─────────────────────────────────────────────────────────
+    build_mols = [Chem.MolFromSmiles(smiles) for smiles in uniques]
+    brics_iter = list(BRICSBuild(build_mols, maxDepth=max_depth))
+
+    # ── 3. Collect results ───────────────────────────────────────────────
+    results: list[dict] = []
+    for b in brics_iter:
+        if isinstance(b, tuple):
+            recipe, mol = b
+            product_smiles = Chem.MolToSmiles(mol)
+            results.append({
+                "product_smiles": product_smiles,
+                "recipe": recipe,
+                "mol": mol,
+            })
+
+    logger.info("New blocks found -> %d", len(brics_iter))
+
+    # ── 4. Save or return ────────────────────────────────────────────────
+    if output_dir is not None:
+        os.makedirs(output_dir, exist_ok=True)
+
+        # Fragments — human-readable, one SMILES per line
+        write_data(uniques, os.path.join(output_dir, "decomposed_unique.txt"))
+
+        # Results table — dataframe-compatible (CSV or Parquet)
+        if results:
+            df_out = pd.DataFrame([
+                {"product_smiles": r["product_smiles"], "recipe": r["recipe"]}
+                for r in results
+            ])
+        else:
+            df_out = pd.DataFrame(columns=["product_smiles", "recipe"])
+
+        if fmt == "parquet":
+            out_path = os.path.join(output_dir, "brics_results.parquet")
+            df_out.to_parquet(out_path, index=False)
+        else:
+            out_path = os.path.join(output_dir, "brics_results.csv")
+            df_out.to_csv(out_path, index=False)
+
+        logger.info(
+            "Saved %d results to %s (decomposed_unique.txt, %s)",
+            len(results), output_dir, os.path.basename(out_path),
+        )
+        return None
+
+    return results
+
+
+if __name__ == "__main__":
+    smiles = read_df("./source.csv", "SMILES")
+    apply_BRICS(smiles)

polyscript/brics/__init__.py

@@ -0,0 +1,48 @@
+"""
+BRICS (Breaking of Retrosynthetically Interesting Chemical Substructures)
+sub-package for PolyScript.
+
+Provides fragment-based decomposition and recombination of molecules:
+
+- :func:`FindBRICSBonds`    — locate cleavable bonds in a molecule.
+- :func:`BreakBRICSBonds`   — break those bonds, returning labelled fragments.
+- :func:`BRICSDecompose`    — full recursive decomposition into BRICS fragments.
+- :func:`BRICSBuild`        — enumerate new molecules by recombining fragments.
+- :func:`BRICSBuildDistribWrite` — build + persist results to disk.
+
+High-level convenience (from ``BRICS_utils``):
+- :func:`apply_BRICS`       — end-to-end: decompose → deduplicate → rebuild.
+- :func:`read_df`           — load a SMILES column from a CSV.
+- :func:`write_data`        — write text / list data to a file.
+"""
+
+from __future__ import annotations
+
+# ── Core BRICS operations ────────────────────────────────────────────────────
+from polyscript.brics.BRICSMod import (
+    BRICSBuild,
+    BRICSBuildDistribWrite,
+    BRICSDecompose,
+    BreakBRICSBonds,
+    FindBRICSBonds,
+)
+
+# ── High-level utilities ─────────────────────────────────────────────────────
+from polyscript.brics.BRICS_utils import (
+    apply_BRICS,
+    read_df,
+    write_data,
+)
+
+__all__ = [
+    # BRICSMod
+    "FindBRICSBonds",
+    "BreakBRICSBonds",
+    "BRICSDecompose",
+    "BRICSBuild",
+    "BRICSBuildDistribWrite",
+    # BRICS_utils
+    "apply_BRICS",
+    "read_df",
+    "write_data",
+]

polyscript/classifier/__init__.py

@@ -0,0 +1,270 @@
+"""Polymer-type classifier based on SMiPoly functional-group logic.
+
+This module provides ``PolyScriptClassifier``, which classifies monomer
+SMILES strings into polymer-relevant functional-group categories (mono-
+and poly-functional, as well as olefinic) using SMARTS patterns and
+exclusion rules derived from SMiPoly, with additional classes from OMG.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+from polyscript.classifier.class_reference import exc_lst, mon_index_map, mon_lst, mon_type_index
+from polyscript.utils.executor import BaseExecutor
+from polyscript.utils.logger import INFO
+from rdkit import Chem
+
+
+class PolyScriptClassifier(BaseExecutor):
+    _log_level = INFO  # class-level default, change via set_log_level()
+
+    def __init__(
+        self,
+        MinFG: int = 2,
+        MaxFG: int = 4,
+        include_carbonate: bool = True,
+        **kwargs,
+    ):
+        """Initialize the PolyScript classifier.
+
+        Args:
+            MinFG: Minimum number of functional groups for
+                poly-functional classification (default 2).
+            MaxFG: Maximum number of functional groups for
+                poly-functional classification (default 4).
+            include_carbonate: If True, append CO and HCHO rows
+                to enable carbonate monomer classification.
+            **kwargs: Passed to ``BaseExecutor.__init__``.
+        """
+        super().__init__(**kwargs)
+        self.MinFG = MinFG
+        self.MaxFG = MaxFG
+        self.mon_lst = mon_lst
+        self.exc_lst = exc_lst
+        self.mon_index_map = mon_index_map
+        self.mon_type_index = mon_type_index
+        self.include_carbonate = include_carbonate
+
+        self.logger.debug(
+            "PolyScriptClassifier initialised (MinFG=%d, MaxFG=%d)", MinFG, MaxFG
+        )
+
+    def _extract_FG(self, mol, patt):
+        """Count non-overlapping functional-group matches for a pattern.
+
+        Filters out consecutive duplicate matches that differ by a single
+        atom shift (symmetric difference of size 2), which typically
+        represent the same functional group seen from a different
+        orientation rather than distinct occurrences.
+
+        Args:
+            mol: An RDKit ``Mol`` object.
+            patt: An RDKit ``Mol`` object representing a SMARTS pattern.
+
+        Returns:
+            int: Number of distinct functional-group matches.
+        """
+        numFG = 0
+        matchs = mol.GetSubstructMatches(
+            patt
+        )  # finding the substructures based on the pattern
+        if len(matchs) >= 2:  # if higher number of substructures are found
+            not_match = []
+            for i in range(0, len(matchs) - 1):
+                # Checks if the current and next match are NOT extensively overlapping by a
+                # single atom shift (i.e., symmetric difference of atom indices is not 2).
+                if len(set(matchs[i]) ^ set(matchs[i + 1])) != 2:
+                    pass
+                else:
+                    not_match.append(i + 1)
+                numFG = len(
+                    [matchs[i] for i in range(0, len(matchs)) if i not in not_match]
+                )
+        else:
+            # if there are only 2 number of matches just add the length as number of functional group
+            numFG = len(matchs)
+        return numFG
+
+    def _get_mono_FG(self, mol, type_index):
+        """Check for mono-functional (single-monomer) classification.
+
+        Tests whether *mol* contains at least one substructure match
+        from the monomer SMARTS list for *type_index* (ignoring
+        duplicate overlaps).  Also verifies that none of the exclusion
+        patterns for that type match.
+
+        Args:
+            mol: An RDKit ``Mol`` object, or ``None``.
+            type_index: String key into ``self.mon_lst`` and
+                ``self.exc_lst`` (e.g. ``"1"`` for vinyl).
+
+        Returns:
+            list: ``[bool, int]`` — the bool is ``True`` if the
+            monomer type is present with no exclusion violations;
+            the int is the total number of raw substructure matches.
+        """
+        if mol is None:
+            return [False, 0]
+        else:
+            chk_c = 0
+            fchk_c = 0
+            chk = []
+            if len(self.mon_lst[str(type_index)]) != 0:
+                for mon in self.mon_lst[str(type_index)]:
+                    patt = Chem.MolFromSmarts(mon)
+                    if mol.HasSubstructMatch(patt):
+                        chk_c = len(mol.GetSubstructMatches(patt))
+                        fchk_c = fchk_c + chk_c
+                        chk_excl = []
+                        for excl in self.exc_lst[str(type_index)]:
+                            excl_patt = Chem.MolFromSmarts(excl)
+                            if mol.HasSubstructMatch(excl_patt):
+                                chk_excl.append(False)
+                            else:
+                                chk_excl.append(True)
+                        if False in chk_excl:
+                            chk.append(False)
+                        else:
+                            chk.append(True)
+                    else:
+                        chk.append(False)
+                if True in chk:
+                    fchk = True
+                else:
+                    fchk = False
+            else:
+                fchk = False
+        return [fchk, fchk_c]
+
+    def _get_poly_FG(self, mol, type_index):
+        """Check for poly-functional (multi-monomer) classification.
+
+        Counts all functional-group matches (using ``_extract_FG``) and
+        requires the total to fall within ``[MinFG, MaxFG]``.  Also
+        validates that none of the exclusion patterns match.
+
+        Args:
+            mol: An RDKit ``Mol`` object, or ``None``.
+            type_index: String key into ``self.mon_lst`` and
+                ``self.exc_lst``.
+
+        Returns:
+            list: ``[bool, int]`` — the bool is ``True`` if the
+            monomer type is present within the FG count range and
+            has no exclusion violations; the int is the count of
+            functional-group matches.
+        """
+        if mol is None:
+            return [False, 0]
+        chk_c = 0  # check count
+        fchk_c = 0  # functional check count
+        if len(self.mon_lst[str(type_index)]) != 0:
+            for mon in self.mon_lst[str(type_index)]:
+                patt = Chem.MolFromSmarts(mon)
+                chk_c = self._extract_FG(mol, patt)
+                fchk_c = fchk_c + chk_c
+            if self.MinFG <= fchk_c <= self.MaxFG:
+                chk = []
+                for excl in self.exc_lst[str(type_index)]:
+                    excl_patt = Chem.MolFromSmarts(excl)
+                    if mol.HasSubstructMatch(excl_patt):
+                        chk.append(False)
+                    else:
+                        chk.append(True)
+                if False in chk:
+                    fchk = False
+                else:
+                    fchk = True
+            else:
+                fchk = False
+        else:
+            fchk = False
+        return [fchk, fchk_c]
+
+    def _classify(self, df, ids, mapper_func):
+        """Apply a classification mapper to a group of monomer types.
+
+        Iterates over the type indices listed in ``self.mon_index_map[ids]``
+        and creates a new DataFrame column for each type name (from
+        ``self.mon_type_index``), populated by applying *mapper_func*
+        to the ``ROMol`` column.
+
+        Args:
+            df: A pandas DataFrame with a ``ROMol`` column.
+            ids: Index into ``self.mon_index_map`` (0 for mono, 1 for poly).
+            mapper_func: Callable ``(mol, type_index) -> [bool, int]``.
+        """
+        for i in self.mon_index_map[ids]:
+            df[self.mon_type_index[str(i)]] = [
+                e[0] for e in df["ROMol"].apply(mapper_func, type_index=i)
+            ]
+
+    def classify(self, df, col_name):
+        """Run full mono- and poly-functional-group classification.
+
+        Parses SMILES in *df[col_name]*, optionally appends CO / HCHO
+        rows for carbonate classification, runs mono-functional
+        (``_get_mono_FG``) and poly-functional (``_get_poly_FG``)
+        classifiers, and returns the enriched DataFrame.
+
+        Args:
+            df: Input DataFrame containing SMILES strings.
+            col_name: Column name holding SMILES strings.
+
+        Returns:
+            pandas.DataFrame: The input DataFrame with additional
+            classification columns (one per monomer type) and the
+            ``ROMol`` column dropped.  Returns the original DataFrame
+            unchanged if *col_name* is not found.
+        """
+        # read source file
+        DF01 = df
+        n_rows = len(DF01)
+        self.logger.info(
+            "Starting classification (%d rows, column='%s')", n_rows, col_name
+        )
+
+        # optionally append CO and HCHO for carbonate classification
+        DF02 = DF01.copy()
+        if col_name in DF02.columns.to_list():
+            if self.include_carbonate:
+                # adding two rows for CO and HCHO that will later be used
+                # to form carbonate with other monomers
+                DFadd = pd.DataFrame(
+                    [
+                        ["[C-]#[O+]"],  # CO
+                        ["C=O"],  # HCHO
+                    ],
+                    columns=[col_name],
+                )
+                DF02 = pd.concat([DF02, DFadd], ignore_index=True)
+                self.logger.debug(
+                    "Appended CO / HCHO rows for carbonate classification"
+                )
+        else:
+            self.logger.error(
+                "Column '%s' not found in dataframe (available: %s)",
+                col_name,
+                DF02.columns.to_list(),
+            )
+            return df
+
+        # drop NA of smiles, and add chemical structure
+        DF02["ROMol"] = DF02[col_name].apply(lambda x: Chem.MolFromSmiles(x))
+        DF02[col_name] = DF02["ROMol"].apply(lambda x: Chem.MolToSmiles(x))
+
+        null_count = DF02["ROMol"].isna().sum()
+        if null_count:
+            self.logger.warning("%d SMILES could not be parsed", null_count)
+
+        # implementing mono func
+        self.logger.debug("Running mono-functional-group classification")
+        self._classify(DF02, 0, self._get_mono_FG)
+
+        # implementing poly func
+        self.logger.debug("Running poly-functional-group classification")
+        self._classify(DF02, 1, self._get_poly_FG)
+
+        DF02 = DF02.drop("ROMol", axis=1)
+        self.logger.info("Classification complete (%d rows)", len(DF02))
+        return DF02