synkit 1.6.5__py3-none-win_amd64.whl

synkit/Synthesis/reactor_utils.py

@@ -0,0 +1,316 @@
+from typing import List
+from collections import Counter
+from synkit.Chem.Reaction.standardize import Standardize
+from synkit.Graph.Matcher.graph_cluster import GraphCluster
+from synkit.IO.chem_converter import rsmi_to_its, gml_to_smart
+
+
+def _get_unique_aam(list_aam: list) -> list:
+    """Retrieves the unique atom-atom mappings (AAM) by clustering a list of
+    ITS graphs.
+
+    This function first converts each item in the provided list of AAM strings to an ITS graph
+    using the `rsmi_to_its` function. Then, it performs iterative clustering of the ITS graphs
+    based on matching nodes and edges, returning a list of unique AAMs based on the clustering results.
+
+    :param list_aam: A list of AAM strings that will be converted to ITS graphs and clustered.
+    :type list_aam: list
+
+    :return: A list of unique AAMs based on the iterative clustering process.
+    :rtype: list
+
+    :raises Exception: If an error occurs during the conversion or clustering process, an exception is raised.
+    """
+    its_list = [rsmi_to_its(i) for i in list_aam]
+
+    cluster = GraphCluster()
+
+    cls, _ = cluster.iterative_cluster(
+        its_list,
+        attributes=None,
+        nodeMatch=cluster.nodeMatch,
+        edgeMatch=cluster.edgeMatch,
+    )
+    unique = []
+    for subset in cls:
+        unique.append(list_aam[list(subset)[0]])
+    return unique
+
+
+def _get_connected_subgraphs(gml: str, invert: bool = False):
+    """Given a GML string, this function returns the number of connected
+    subgraphs based on the 'smart' representation split or a list of subgraphs,
+    depending on the invert flag.
+
+    :param gml: GML string to convert to SMARTS.
+    :type gml: str
+    :param invert: Count product components instead of reactant components.
+    :type invert: bool
+    :return: Number of connected components on the selected reaction side.
+    :rtype: int
+    :raises ValueError: If ``gml`` is empty or lacks the ``>>`` delimiter.
+    """
+    # Validate GML input (ensure it's a valid non-empty string)
+    if not isinstance(gml, str) or not gml.strip():
+        raise ValueError("Invalid GML string provided.")
+
+    # Convert GML to 'smart' representation
+    smart = gml_to_smart(gml, sanitize=False)
+
+    # Split the 'smart' string by the delimiter '>>' to get the left (r) and right (p) parts
+    try:
+        left_part, right_part = smart.split(">>")
+    except ValueError:
+        raise ValueError("GML string does not contain the expected '>>' delimiter.")
+
+    # Handle the result based on the invert flag
+    if invert:
+        # Return the count of subgraphs in the right part (p)
+        return len(right_part.split("."))
+    else:
+        # Return a list of subgraphs from the left part (r)
+        return len(left_part.split("."))
+
+
+def _get_reagent(original_smiles: list, output_rsmi: str, invert: bool = False):
+    """Identifies reagents present in the original SMILES list that are absent
+    in the processed output SMILES string.
+
+    :param original_smiles: list of SMILES strings representing the original reagents.
+    :param output_rsmi: SMILES string of the reaction, which is standardized and split to obtain new SMILES strings.
+    :param invert: bool, flag to choose between reactants or products for comparison.
+
+    :return: List of SMILES strings found in original but not in the new list.
+    """
+    output_rsmi = Standardize().fit(output_rsmi)
+    reactants, products = output_rsmi.split(">>")
+    smiles = products.split(".") if invert else reactants.split(".")
+
+    # Use Counter to find differences
+    original_count = Counter(original_smiles)
+    new_count = Counter(smiles)
+    reagent_difference = (
+        original_count - new_count
+    )  # Subtract counts to find unique in original
+
+    # Extract unique reagents
+    unique_reagents = list(reagent_difference.elements())
+
+    return unique_reagents
+
+
+def _get_reagent_rsmi(rsmi: str) -> List[str]:
+    """Identifies reagents that appear in both the reactant and product sides
+    of a reaction SMILES string, suggesting these elements are unchanged by the
+    chemical reaction.
+
+    :param rsmi: A reaction SMILES string formatted as "reactants>>products".
+    :type rsmi: str
+
+    :return: A list of unique reagents that appear on both sides of the reaction, unchanged.
+    :rtype: List[str]
+    """
+    # Standardize the input reaction SMILES
+    rsmi = Standardize().fit(rsmi)
+
+    # Splitting the standardized rSMI into reactants and products
+    reactants, products = rsmi.split(">>")
+    reactants = reactants.split(".")
+    products = products.split(".")
+
+    # Count occurrences of each molecule in reactants and products
+    reactants_count = Counter(reactants)
+    products_count = Counter(products)
+
+    # Find common elements in reactants and products
+    common_elements = reactants_count & products_count  # Use intersection
+
+    # Extract and return the unique reagents that are common
+    unique_reagents = list(common_elements.elements())
+
+    return unique_reagents
+
+
+def _remove_reagent(rsmi: str) -> str:
+    """Removes common molecules from the reactants and products in a SMILES
+    reaction string.
+
+    This function identifies the molecules that appear on both sides of the reaction
+    (reactants and products) and removes one occurrence of each common molecule from
+    both sides.
+
+    :param rsmi: A SMILES string representing a chemical reaction in the form:
+                 'reactant1.reactant2...>>product1.product2...'
+    :type rsmi: str
+
+    :return: Reaction SMILES with common molecules removed from both sides.
+
+              Example: >>> remove_reagent_from_smiles('CC=O.CC=O.CCC=O>>CC=CO.CC=O.CC=O') 'CCC=O>>CC=CO'
+    :rtype: str
+    """
+
+    # Split the input SMILES string into reactants and products
+    reactants, products = rsmi.split(">>")
+
+    # Split the reactants and products by '.' to separate molecules
+    reactant_molecules = reactants.split(".")
+    product_molecules = products.split(".")
+
+    # Count the occurrences of each molecule in reactants and products
+    reactant_count = Counter(reactant_molecules)
+    product_count = Counter(product_molecules)
+
+    # Find common molecules between reactants and products
+    common_molecules = set(reactant_count) & set(product_count)
+
+    # Remove common molecules by the minimum occurrences in both reactants and products
+    for molecule in common_molecules:
+        common_occurrences = min(reactant_count[molecule], product_count[molecule])
+
+        # Decrease the count by the common occurrences
+        reactant_count[molecule] -= common_occurrences
+        product_count[molecule] -= common_occurrences
+
+    # Rebuild the lists of reactant and product molecules after removal
+    filtered_reactant_molecules = [
+        molecule for molecule, count in reactant_count.items() for _ in range(count)
+    ]
+    filtered_product_molecules = [
+        molecule for molecule, count in product_count.items() for _ in range(count)
+    ]
+
+    # Join the remaining molecules back into SMILES strings
+    new_reactants = ".".join(filtered_reactant_molecules)
+    new_products = ".".join(filtered_product_molecules)
+
+    # Return the updated reaction string
+    return f"{new_reactants}>>{new_products}"
+
+
+def _add_reagent(rsmi: str, reagents: list):
+    """Modifies the SMILES representation of a reaction by adding additional
+    reagents.
+
+    :param rsmi: str, the SMILES reaction string, expected to contain '>>' separating reactants and products.
+    :param reagents: list, a list of reagent SMILES strings to be added.
+
+    :return: a new SMILES string with reagents added to both reactants and products.
+    :rtype: str
+    """
+    if not reagents:
+        return rsmi  # Return original if no reagents are added
+
+    try:
+        reactants, products = rsmi.split(">>")
+    except ValueError:
+        raise ValueError("Input SMILES string does not contain '>>'")
+
+    # Prepare the reagents string only once
+    reagents_string = ".".join(reagents)
+
+    # Incorporate reagents into both reactants and products
+    modified_reactants = (
+        f"{reactants}.{reagents_string}" if reactants else reagents_string
+    )
+    modified_products = f"{products}.{reagents_string}" if products else reagents_string
+
+    return f"{modified_reactants}>>{modified_products}"
+
+
+def _calculate_max_depth(reaction_tree, current_node=None, depth=0):
+    """Calculate the maximum depth of a reaction tree.
+
+    :param reaction_tree: A dictionary where keys are reaction SMILES (RSMI)
+                          and values are lists of product reactions.
+    :type reaction_tree: dict
+    :param current_node: The current node in the tree being explored (reaction SMILES).
+    :type current_node: str
+    :param depth: The current depth of the tree.
+    :type depth: int
+
+    :return: The maximum depth of the tree.
+    :rtype: int
+    """
+    # If current_node is None, start from the root node (first key in the reaction tree)
+    if current_node is None:
+        current_node = list(reaction_tree.keys())[0]
+
+    # Get the products of the current node (reaction)
+    products = reaction_tree.get(current_node, [])
+
+    # If no products, we are at a leaf node, return the current depth
+    if not products:
+        return depth
+
+    # Recursively calculate the depth for each product and return the maximum
+    max_subtree_depth = max(
+        _calculate_max_depth(reaction_tree, product, depth + 1) for product in products
+    )
+    return max_subtree_depth
+
+
+def _find_all_paths(
+    reaction_tree,
+    target_products,
+    current_node,
+    target_depth,
+    current_depth=0,
+    path=None,
+):
+    """Recursively find all paths from the root to the maximum depth in the
+    reaction tree.
+
+    :param reaction_tree: A dictionary of reaction SMILES with products.
+    :type reaction_tree: dict
+    :param current_node: The current node (reaction SMILES).
+    :type current_node: str
+    :param target_depth: The depth at which the product matches the root's product.
+    :type target_depth: int
+    :param current_depth: The current depth of the search.
+    :type current_depth: int
+    :param path: The current path in the tree.
+    :type path: list
+
+    :return: List of all paths to the max depth.
+    """
+    if path is None:
+        path = []
+
+    # Add the current node (reaction SMILES) to the path
+    path.append(current_node)
+
+    # If we have reached the target depth, check the product
+    if current_depth == target_depth:
+        # Extract products of the current node
+        current_products = sorted(
+            current_node.split(">>")[1].split("."), key=len
+        )  # Sort by length of SMILES
+        largest_current_product = current_products[-1] if current_products else None
+
+        # Process target_products to get the largest product
+
+        sorted_target_products = sorted(
+            target_products, key=len
+        )  # target_products should be a string here
+
+        largest_target_product = (
+            sorted_target_products[-1] if sorted_target_products else None
+        )
+
+        # Compare the largest elements
+        return [path] if largest_current_product == largest_target_product else []
+
+    # If we haven't reached the target depth, recurse on the products
+    paths = []
+    for product in reaction_tree.get(current_node, []):
+        paths.extend(
+            _find_all_paths(
+                reaction_tree,
+                target_products,
+                product,
+                target_depth,
+                current_depth + 1,
+                path.copy(),
+            )
+        )
+    return paths

synkit/Utils/utils.py

@@ -0,0 +1,172 @@
+import random
+from typing import Dict, List, Optional
+from datetime import datetime
+import networkx as nx
+from typing import Iterable
+
+
+def stratified_random_sample(
+    data: List[Dict[str, any]],
+    property_key: str,
+    samples_per_class: int = 1,
+    seed: Optional[int] = 42,
+    bypass: bool = False,
+) -> List[Dict[str, any]]:
+    """Stratifies and samples data from a list of dictionaries based on a
+    specified property key.
+
+    :param data: The data to sample from, a list of dictionaries.
+    :type data: List[Dict[str, any]]
+    :param property_key: The key in the dictionaries to stratify by.
+    :type property_key: str
+    :param samples_per_class: The number of samples to take from each class.
+                              Defaults to 1.
+    :type samples_per_class: int
+    :param seed: The seed for the random number generator
+                 for reproducibility. Defaults to 42.
+    :type seed: Optional[int], optional
+    :param bypass: If True, classes with fewer than
+                   `samples_per_class` entries will be skipped without raising an error.
+                   Defaults to False.
+    :type bypass: bool, optional
+
+    :return: A list of sampled dictionaries, where each entry corresponds to a sampled item.
+    :rtype: List[Dict[str, any]]
+
+    :raises ValueError: If a class has fewer than `samples_per_class` entries and `bypass` is False.
+    """
+
+    if seed is not None:
+        random.seed(seed)
+
+    stratified_data = {}
+    for item in data:
+        key = item.get(property_key)
+        if key is None:
+            continue  # Exclude data items where the specified key is not present
+        if key in stratified_data:
+            stratified_data[key].append(item)
+        else:
+            stratified_data[key] = [item]
+
+    sampled_data = []
+    for key, items in stratified_data.items():
+        class_size = len(items)
+        if class_size >= samples_per_class:
+            sampled_data.extend(random.sample(items, samples_per_class))
+        elif bypass:
+            continue  # Skip this group entirely if not enough data and bypass is True
+        else:
+            raise ValueError(
+                f"Not enough data to sample {samples_per_class} items for class '{key}', "
+                f"only {class_size} available."
+            )
+
+    return sampled_data
+
+
+def calculate_processing_time(start_time_str: str, end_time_str: str) -> float:
+    """Calculates the processing time in seconds between two timestamps.
+
+    :param start_time_str: A string representing the start time in the format
+                           'YYYY-MM-DD HH:MM:SS,fff'.
+    :type start_time_str: str
+    :param end_time_str: A string representing the end time in the same format as
+                         start_time_str.
+    :type end_time_str: str
+
+    :return: The duration between the start and end time in seconds.
+    :rtype: float
+
+    :raises ValueError: If the input strings do not match the expected format.
+    """
+    datetime_format = "%Y-%m-%d %H:%M:%S,%f"
+
+    start_time = datetime.strptime(start_time_str, datetime_format)
+    end_time = datetime.strptime(end_time_str, datetime_format)
+
+    duration = end_time - start_time
+
+    return duration.total_seconds()
+
+
+def remove_explicit_hydrogen(
+    Graph: nx.Graph, excluded_indices: Iterable[int]
+) -> nx.Graph:
+    """Processes a molecular graph by calculating hydrogen count ('h_count')
+    for each node and removing hydrogen nodes that are not specified in the
+    excluded indices.
+
+    :param Graph: The input graph with nodes expected to have an 'element' attribute.
+    :type Graph: nx.Graph
+    :param excluded_indices: Indices of hydrogen nodes to be preserved and excluded from 'h_count' calculations.
+    :type excluded_indices: Iterable[int]
+
+    :return: The modified graph where each node has an 'h_count' attribute indicating the count
+              of hydrogen neighbors, and specific hydrogens have been removed unless listed in
+              excluded_indices.
+    :rtype: nx.Graph
+
+    .. rubric:: Notes
+
+    This function operates on a copy of the input graph and does not alter the original.
+    """
+    G = Graph.copy()
+
+    # Calculate h_count for each node
+    for node in list(G.nodes):
+        h_count = 0
+        for neighbor in G.neighbors(node):
+            if (
+                G.nodes[neighbor].get("element") == "H"
+                and neighbor not in excluded_indices
+            ):
+                h_count += 1
+        G.nodes[node]["hcount"] = h_count
+
+    # Remove hydrogen nodes not in excluded indices
+    nodes_to_remove = [
+        n
+        for n in G.nodes
+        if G.nodes[n].get("element") == "H" and n not in excluded_indices
+    ]
+    G.remove_nodes_from(nodes_to_remove)
+
+    return G
+
+
+def fix_implicit_hydrogen(Graph: nx.Graph, indices: Iterable[int]) -> nx.Graph:
+    """Adjusts the 'h_count' attribute of specific nodes in a molecular graph,
+    decreasing it based on the presence of neighboring hydrogen atoms that are
+    also included in the specified indices. This function works on a copy of
+    the provided graph and returns the modified copy.
+
+    :param Graph: Graph whose nodes contain ``element`` and optionally
+                  ``hcount`` attributes.
+    :type Graph: nx.Graph
+    :param indices: Nodes whose neighboring explicit hydrogens should reduce
+                    their implicit hydrogen count.
+    :type indices: Iterable[int]
+    :return: Graph copy with adjusted ``hcount`` values.
+    :rtype: nx.Graph
+
+    .. rubric:: Notes
+
+    Ensure the 'hcount' exists and is appropriately structured before using this
+    function. It is assumed that 'hcount' is a mutable integer that can be directly
+    decremented.
+    """
+    G = Graph.copy()  # Work on a copy of the graph to preserve the original
+    valid_indices = set(indices).intersection(
+        G.nodes
+    )  # Ensure node indices exist in the graph
+
+    for node in valid_indices:
+        if "hcount" in G.nodes[node]:  # Ensure the node has an 'h_count' to modify
+            for neighbor in G.neighbors(node):
+                # Check if neighbor is hydrogen and also in indices
+                if G.nodes[neighbor].get("element") == "H" and neighbor in indices:
+                    if G.nodes[node].get("element") != "H":
+                        G.nodes[node]["hcount"] -= 1
+
+    return G

synkit/Vis/__init__.py

@@ -0,0 +1,91 @@
+"""Visualization APIs.
+
+The preferred domain namespaces are:
+
+* :mod:`synkit.Vis.molecule` for molecule and reaction graph panels.
+* :mod:`synkit.Vis.its` for ITS visualizations.
+* :mod:`synkit.Vis.mtg` for MTG timeline and step visualizations.
+* :mod:`synkit.Vis.epd` for electron-pushing diagrams.
+* :mod:`synkit.Vis.reaction` for RDKit reaction and rule images.
+* :mod:`synkit.Vis.space` for chemical-space plots and embeddings.
+* :mod:`synkit.Vis.crn` for chemical reaction network visualizations.
+
+Flat imports from :mod:`synkit.Vis` remain supported for the public drawing
+functions exported below.
+"""
+
+from .graph_visualizer import GraphVisualizer
+from .reaction import RXNVis, RuleVis
+from .space import Embedding, adjust_legend_handles, scatter_plot
+from .crn import CRNStyle, CRNVis, draw_crn
+from .visual_model import (
+    VisualEdge,
+    VisualGraph,
+    VisualKind,
+    VisualNode,
+    detect_visual_kind,
+    iter_changed_edges,
+    iter_changed_nodes,
+    summarize_visual_graph,
+    to_visual_graph,
+)
+from .visual_drawer import draw_graph
+from .molecule import draw_molecule_graph
+from .molecule import (
+    ReactionHighlights,
+    draw_reaction_graph,
+    draw_reaction_graphs,
+    find_reaction_highlights,
+)
+from .its import draw_its_from_rsmi, draw_its_graph, draw_its_only
+from .mtg import draw_mtg_graph, draw_mtg_steps
+from .epd import (
+    MechanismVisualizer,
+    Transition,
+    transition_from_epd_step,
+    transitions_from_epd,
+)
+from . import crn, epd, its, molecule, mtg, reaction, space
+
+__all__ = [
+    "GraphVisualizer",
+    "RuleVis",
+    "RXNVis",
+    "Embedding",
+    "CRNStyle",
+    "CRNVis",
+    "draw_crn",
+    "VisualEdge",
+    "VisualGraph",
+    "VisualKind",
+    "VisualNode",
+    "detect_visual_kind",
+    "iter_changed_edges",
+    "iter_changed_nodes",
+    "summarize_visual_graph",
+    "to_visual_graph",
+    "draw_graph",
+    "draw_molecule_graph",
+    "ReactionHighlights",
+    "draw_reaction_graph",
+    "draw_reaction_graphs",
+    "find_reaction_highlights",
+    "draw_its_from_rsmi",
+    "draw_its_graph",
+    "draw_its_only",
+    "draw_mtg_graph",
+    "draw_mtg_steps",
+    "MechanismVisualizer",
+    "Transition",
+    "transition_from_epd_step",
+    "transitions_from_epd",
+    "scatter_plot",
+    "adjust_legend_handles",
+    "molecule",
+    "its",
+    "mtg",
+    "epd",
+    "reaction",
+    "space",
+    "crn",
+]

synkit/Vis/crn/__init__.py

@@ -0,0 +1,40 @@
+"""Chemical reaction network visualization namespace.
+
+This namespace re-exports :mod:`synkit.CRN.Visualize`, which is the single CRN
+visualizer in SynKit. It draws the species--reaction bipartite graph of a
+:class:`~synkit.CRN.Structure.syncrn.SynCRN` (or any equivalent NetworkX
+digraph) with layered layout, palettes and highlighting.
+
+.. rubric:: Example
+
+.. code-block:: python
+
+    from synkit.CRN import SynCRN
+    from synkit.Vis.crn import draw_crn
+
+    draw_crn(SynCRN.from_reaction_strings(["A>>B", "B>>C"]).to_digraph())
+
+.. rubric:: Removed
+
+``CRNVisualizer`` has been removed. It plotted the ``dev_crn`` hypergraph
+object, which no longer exists in the package, so every call raised
+``AttributeError``. Use :class:`~synkit.CRN.Visualize.vis.CRNVis` instead.
+"""
+
+from synkit.CRN.Visualize import (
+    ColorPalette,
+    CRNStyle,
+    CRNVis,
+    draw_crn,
+    get_palette,
+    palette_names,
+)
+
+__all__ = [
+    "CRNStyle",
+    "CRNVis",
+    "ColorPalette",
+    "draw_crn",
+    "get_palette",
+    "palette_names",
+]

synkit/Vis/epd/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+"""Visualization submodule for mechanism trajectories.
+
+Main entry points
+-----------------
+- :class:`MechanismVisualizer`
+- :class:`Transition`
+- :func:`transitions_from_epd`
+"""
+
+from .models import Transition, transition_from_epd_step, transitions_from_epd
+from .visualizer import MechanismVisualizer
+
+__all__ = [
+    "MechanismVisualizer",
+    "Transition",
+    "transition_from_epd_step",
+    "transitions_from_epd",
+]