assemblycfg 1.2.2__tar.gz

assemblycfg-1.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ELIFE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

assemblycfg-1.2.2/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: assemblycfg
+Version: 1.2.2
+Summary: Place upper bounds on assembly index using the grammar algorithm RePair.
+Author: Gage Siebert, Redwan Chowdhury, Louie Slocombe, Sara I. Walker
+License: MIT
+Project-URL: Homepage, https://github.com/ELIFE-ASU/assemblycfg
+Project-URL: Repository, https://github.com/ELIFE-ASU/assemblycfg
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=3.4.2
+Requires-Dist: matplotlib>=3.9.2
+Requires-Dist: rdkit>=2024.03.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4.2; extra == "dev"
+Dynamic: license-file
+
+# Context-Free Grammars and String Assembly Index
+
+Directed string assembly index calculator using the smallest grammar algorithm RePair. This will quickly find a short assembly path, but there is no guarantee that it will find the shortest possible assembly path. Thus, this path length serves as an upper bound to the assembly index. This method works best on strings but can also be applied to molecular graphs as we will demonstrate below.
+
+## Installation
+
+Prerequisites: 
+networkx >= 3.4.2
+rdkit >=2024.03.5
+matplotlib>=3.9.2
+
+Use pip to install this package.
+
+```
+pip install assemblycfg
+```
+
+## Examples
+
+The central function of this package, `cfg.repair_with_pathways` returns three items. First it returns the integer path length with upper bounds the assembly index, second it returns the list of virtual object strings which were used along the assembly path identified by RePair, and third it returns a networkx DiGraph object depicting the assembly path.
+
+```
+import assemblycfg as cfg
+l, vo, path = cfg.repair_with_pathways("abracadabra")
+print(f'a("abracadabra") =< {l}')
+print(f"Virtual objects used: {vo}")
+```
+You can visualize the pathway as follows
+```
+import networkx as nx
+import matplotlib.pyplot as plt
+nx.draw(path, with_labels=True, font_weight='bold', pos=nx.spring_layout(path))
+plt.show()
+```
+though these pathway visuals easy get unweildy. We recommend the python package AssemblyTheoryTools for more sophisticated pathway plotting functions.
+
+One can also apply these methods to molecular assembly index. The function `calculate_assembly_path_det` can place a valid upper bound on the assembly index of any molecule, though it performs best on 'stringy' molecules like lipids. Starting from a SMILES string for cholesterol, we convert it into a networkx graph format before passing it to the calculator.
+```
+import assemblycfg as cfg
+smi_str = "C[C@H](CCCC(C)C)[C@H]1CC[C@@H]2[C@@]1(CC[C@H]3[C@H]2CC=C4[C@@]3(CC[C@@H](C4)O)C)C" # SMILES string for cholesterol
+molgraph = cfg.smi_to_nx(smi_to_nx)
+l, vo, path = cfg.calculate_assembly_path_det(molgraph)
+print(f'a(Cholesterol) =< {l}')
+```
+These virtual objects will also be networkx graphs representing molecular fragments.
+
+See the examples folder for more examples of how to use the package.
+
+These algorithms are described in Siebert et al. (In Prep); if you find this package useful, please cite this paper.

assemblycfg-1.2.2/README.md

@@ -0,0 +1,49 @@
+# Context-Free Grammars and String Assembly Index
+
+Directed string assembly index calculator using the smallest grammar algorithm RePair. This will quickly find a short assembly path, but there is no guarantee that it will find the shortest possible assembly path. Thus, this path length serves as an upper bound to the assembly index. This method works best on strings but can also be applied to molecular graphs as we will demonstrate below.
+
+## Installation
+
+Prerequisites: 
+networkx >= 3.4.2
+rdkit >=2024.03.5
+matplotlib>=3.9.2
+
+Use pip to install this package.
+
+```
+pip install assemblycfg
+```
+
+## Examples
+
+The central function of this package, `cfg.repair_with_pathways` returns three items. First it returns the integer path length with upper bounds the assembly index, second it returns the list of virtual object strings which were used along the assembly path identified by RePair, and third it returns a networkx DiGraph object depicting the assembly path.
+
+```
+import assemblycfg as cfg
+l, vo, path = cfg.repair_with_pathways("abracadabra")
+print(f'a("abracadabra") =< {l}')
+print(f"Virtual objects used: {vo}")
+```
+You can visualize the pathway as follows
+```
+import networkx as nx
+import matplotlib.pyplot as plt
+nx.draw(path, with_labels=True, font_weight='bold', pos=nx.spring_layout(path))
+plt.show()
+```
+though these pathway visuals easy get unweildy. We recommend the python package AssemblyTheoryTools for more sophisticated pathway plotting functions.
+
+One can also apply these methods to molecular assembly index. The function `calculate_assembly_path_det` can place a valid upper bound on the assembly index of any molecule, though it performs best on 'stringy' molecules like lipids. Starting from a SMILES string for cholesterol, we convert it into a networkx graph format before passing it to the calculator.
+```
+import assemblycfg as cfg
+smi_str = "C[C@H](CCCC(C)C)[C@H]1CC[C@@H]2[C@@]1(CC[C@H]3[C@H]2CC=C4[C@@]3(CC[C@@H](C4)O)C)C" # SMILES string for cholesterol
+molgraph = cfg.smi_to_nx(smi_to_nx)
+l, vo, path = cfg.calculate_assembly_path_det(molgraph)
+print(f'a(Cholesterol) =< {l}')
+```
+These virtual objects will also be networkx graphs representing molecular fragments.
+
+See the examples folder for more examples of how to use the package.
+
+These algorithms are described in Siebert et al. (In Prep); if you find this package useful, please cite this paper.

assemblycfg-1.2.2/assemblycfg/__init__.py

@@ -0,0 +1,20 @@
+from .cfg_ai import (ai_core, repair_with_pathways)
+
+from .det import (calculate_assembly_path_det)
+
+from .utils import (safe_standardize_mol,
+                    smi_to_mol,
+                    smi_to_nx,
+                    mol_to_nx,
+                    remove_hydrogen_from_graph,
+                    bond_order_rdkit_to_int,
+                    get_disconnected_subgraphs,
+                    molfile_to_mol,
+                    standardize_mol,
+                    nx_to_dict,
+                    dict_to_nx,
+                    mol2graph,
+                    print_graph_dict,
+                    print_virtual_objects)
+
+__version__ = "1.2.1"

assemblycfg-1.2.2/assemblycfg/cfg_ai.py

@@ -0,0 +1,421 @@
+import collections
+import string
+from typing import List, Tuple, Dict, Union
+
+import networkx as nx
+
+
+def rules_to_graph(rules: List[str],
+                   virt_obj: List[str]) -> nx.DiGraph:
+    """
+    Convert a list of join rules into a NetworkX directed graph and add virtual nodes.
+
+    Parses rules in the form ``"A + B = C"`` and adds directed edges ``A -> C`` and
+    ``B -> C`` for each rule. Virtual objects are added to the graph as isolated
+    nodes (if not already present).
+
+    Parameters
+    ----------
+    rules : list of str
+        Sequence of rules where each rule is expected to contain two operands and
+        a result using the literal separators ``' + '`` and `` = '`` (e.g.
+        ``"A + B = C"``). Empty list is accepted and yields a graph containing only
+        the provided ``virt_obj`` nodes.
+    virt_obj : list of str
+        Sequence of virtual object identifiers to be added as nodes to the graph.
+        Nodes that also appear in parsed rules are not duplicated.
+
+    Returns
+    -------
+    networkx.DiGraph
+        A directed graph with nodes for all operands, results and virtual objects.
+        For each rule ``"A + B = C"`` there will be edges ``A -> C`` and ``B -> C``.
+
+    Raises
+    ------
+    ValueError
+        If a rule does not contain exactly two operands and one result when split
+        using the expected separators (e.g. malformed string).
+    """
+    # Create a directed graph and add virtual objects as nodes
+    graph = nx.DiGraph()
+    graph.add_nodes_from(virt_obj)
+
+    # Add edges based on rules
+    for rule in rules:
+        a, b, c = rule.replace(" + ", " = ").split(" = ")
+        graph.add_edge(a, c)
+        graph.add_edge(b, c)
+
+    return graph
+
+
+def repair(s: Union[str, list[str]]) -> Tuple[List[List[str]], Dict[str, List[str]]]:
+    """
+    Iteratively replace the most frequent adjacent symbol pairs in a string with new non-terminal symbols.
+
+    Scans the input string for adjacent symbol pairs, identifies pairs that occur more than
+    once, and replaces the most frequent pair with a freshly introduced non-terminal
+    (e.g. ``A1``, ``A2``). Replacements are applied repeatedly until no pair occurs
+    more than once. Returns the resulting symbol sequence and a mapping of introduced
+    non-terminals to the pair they replaced.
+
+    Parameters
+    ----------
+    s : str or list of str
+        Input string of symbols (each character treated as a symbol). The function
+        operates on single-character symbols and produces new multi-character
+        non-terminal symbols of the form ``A{n}``.
+
+    Returns
+    -------
+    symbols : list of str
+        Sequence of symbols after all replacements. Contains original terminal
+        symbols and introduced non-terminal symbols (strings like ``'A1'``).
+    productions : dict
+        Mapping from introduced non-terminal symbol to the two-symbol list it
+        replaces, e.g. ``{'A1': ['a', 'b']}``.
+
+    Raises
+    ------
+    TypeError
+        If ``s`` is not a string.
+    """
+    if isinstance(s, str):
+        symbols: List[List[str]] = [list(s)]
+    else:
+        if not all(isinstance(subs, str) for subs in s):
+            raise TypeError("Input must be a string or a list of strings.")
+        symbols: List[List[str]] = [list(subs) for subs in s]
+
+    # Input safety check
+    for symbol in symbols:
+        for s in symbol:
+            assert s in string.ascii_lowercase, "Input string must consist of lowercase ASCII characters only."
+
+    productions: Dict[str, List[str]] = {}
+    non_terminal_counter: int = 1
+
+    while True:
+        # Count the frequency of adjacent pairs and filter those occurring more than once
+
+        pair_counts = collections.Counter()
+        for subs in symbols:
+            pair_counts.update(zip(subs, subs[1:]))
+
+        frequent_pairs = {pair: count for pair, count in pair_counts.items() if count > 1}
+
+        if not frequent_pairs:
+            break
+
+        # Find the most frequent pair and create a new non-terminal
+        most_frequent_pair = max(frequent_pairs, key=frequent_pairs.get)
+        new_non_terminal = f'A{non_terminal_counter}'
+        non_terminal_counter += 1
+        productions[new_non_terminal] = list(most_frequent_pair)
+
+        for idx, subs in enumerate(symbols):
+            i = 0
+            while i < len(subs) - 1:
+                # Check if the current pair matches the most frequent pair
+                if (subs[i], subs[i + 1]) == most_frequent_pair:
+                    # Replace the pair with the new non-terminal
+                    subs[i:i + 2] = [new_non_terminal]
+                    i = max(i - 1, 0)  # Step back to handle overlapping pairs
+                else:
+                    i += 1
+            symbols[idx] = subs
+
+    return symbols, productions
+
+
+def convert_to_cnf(start_symbols: Union[str, List[str]],
+                   productions: Dict[str, List[str]]) -> Tuple[str, Dict[str, List[str]]]:
+    """
+    Convert a context-free grammar (CFG) to Chomsky Normal Form (CNF).
+
+    Transforms the given productions by:
+    - mapping lowercase terminal symbols to fresh terminal non-terminals of the form ``T_<symbol>``;
+    - introducing new non-terminals ``N<n>`` to break right-hand sides longer than two into binary rules;
+    - ensuring a single start non-terminal (``S``) whose right-hand side has length one or two.
+
+    Parameters
+    ----------
+    start_symbols : Union[str, List[str]]
+        The start symbol or start sequence of symbols for the grammar. Can be a
+        string (each character treated as a symbol) or a list of symbol strings.
+    productions : dict
+        Mapping from non-terminal symbols (keys) to lists of symbols (values). Each value is a list
+        representing the right-hand side of a production. Terminals are assumed to be lowercase ASCII
+        characters; other strings are treated as non-terminals.
+
+    Returns
+    -------
+    start_nts : str
+        The new start non-terminal (conventionally ``S``).
+    cnf_productions : dict
+        A dictionary mapping non-terminals to CNF-compliant right-hand sides. Right-hand sides are
+        either a single terminal (e.g. ``['T_a']``) or two non-terminals (e.g. ``['N1', 'B']``).
+        Terminal mappings for each original terminal are included as productions (``'T_a': ['a']``).
+
+    Raises
+    ------
+    TypeError
+        If ``start_symbol`` is not a string or if ``productions`` is not a mapping of non-terminals to lists.
+    ValueError
+        If a production contains an empty right-hand side.
+
+    """
+    cnf_productions: Dict[str, List[str]] = {}
+    new_nt_counter: int = 1
+
+    if isinstance(start_symbols, str):
+        start_symbols = list(start_symbols)
+
+    # Map terminals to new non-terminals
+    terminals = {s for exp in productions.values() for s in exp if s in string.ascii_lowercase}
+    for start_symbol in start_symbols:
+        terminals.update(s for s in start_symbol if s in string.ascii_lowercase)
+    terminal_map: Dict[str, str] = {t: f'T_{t}' for t in terminals}
+    cnf_productions.update({nt: [t] for t, nt in terminal_map.items()})
+
+    def replace_terminals(symbols: List[str]) -> List[str]:
+        return [terminal_map.get(s, s) for s in symbols]
+
+    # Convert productions to CNF
+    for nt, expansion in productions.items():
+        expansion = replace_terminals(expansion)
+        while len(expansion) > 2:
+            new_nt = f'N{new_nt_counter}'
+            cnf_productions[new_nt] = expansion[:2]
+            expansion = [new_nt] + expansion[2:]
+            new_nt_counter += 1
+        cnf_productions[nt] = expansion
+
+    # Handle the start symbol
+    for idx, word in enumerate(start_symbols):
+        word = replace_terminals(list(word))
+        start_nt = 'S_' + str(idx)
+        while len(word) > 2:
+            new_nt = f'N{new_nt_counter}'
+            cnf_productions[new_nt] = word[:2]
+            word = [new_nt] + word[2:]
+            new_nt_counter += 1
+        cnf_productions[start_nt] = word
+
+    return start_nt, cnf_productions
+
+
+def ai_core(s: Union[str, List[str]],
+            debug: bool = False) -> Tuple[int, Dict[str, List[str]]]:
+    """
+    Convert an input string into Chomsky Normal Form (CNF) and compute a production count.
+
+    This function performs a two-stage transformation: it first derives a set of
+    productions and an augmented start symbol using the `repair` routine, then
+    transforms those productions into CNF using `convert_to_cnf`. It also returns
+    a scalar measure (`ai_count`) derived from the intermediate start symbol and
+    the number of introduced productions.
+
+    Parameters
+    ----------
+    s : Union[str, List[str]]
+        Input string of symbols to be processed. Each character is treated as a
+        terminal symbol for the initial `repair` pass.
+    debug : bool, optional
+        If True, print intermediate values (start symbol, productions, CNF
+        productions and their lengths) to stdout for debugging. Default is False.
+
+    Returns
+    -------
+    ai_count : int
+        Integer count computed as `len(start_symbol) - 1 + len(productions)` where
+        `start_symbol` and `productions` are the outputs of `repair(s)`. Intended
+        as a simple complexity/path-length metric used by downstream logic.
+    cnf_productions : dict
+        Mapping of non-terminal symbols to CNF-compliant right-hand sides. Each
+        value is a list of one terminal-nonterminal mapping (e.g. ``['T_a']``) or
+        two non-terminals (e.g. ``['N1', 'B']``).
+
+    Raises
+    ------
+    TypeError
+        If ``s`` is not a string or a list of strings.
+    """
+    start_symbols, productions = repair(s)
+    start_nts, cnf_productions = convert_to_cnf(start_symbols, productions)
+    if debug:
+        print(f"Start symbols: {start_symbols}", flush=True)
+        print(f"Productions: {productions}", flush=True)
+        print(f"Length of Productions: {len(productions)}", flush=True)
+        print(f"CNF Productions: {cnf_productions}", flush=True)
+        print(f"Length of CNF Productions: {len(cnf_productions)}", flush=True)
+    # return len(cnf_productions) - len(set(s)), cnf_productions
+
+    # Use temp to count number of terminal symbols (ai = # of non-terminal producing cnf production rules)
+    temp = ""
+    for obj in set(s):
+        temp += obj
+
+    return len(cnf_productions) - len(set(temp)), cnf_productions
+
+
+def get_rules(s: Union[str, List[str]],
+              production: Dict[str, List[str]],
+              f_print: bool = False) -> List[str]:
+    """
+    Generate join rules from productions by performing a topological sort.
+
+    Performs a Kahn-style topological traversal over the dependency graph
+    defined by `production` and the initial symbols in `s`. Builds string
+    mappings for intermediate non-terminals and emits join rules of the form
+    ``"<left> + <right> = <result>"`` when a non-terminal expands to two symbols.
+
+    Parameters
+    ----------
+    s : Union[str, List[str]]
+        Input string or list of strings being processed.
+    production : dict
+        Mapping from non-terminal symbol to its right-hand side as a list of
+        symbols. Right-hand sides are expected to be length 1 or 2. Keys that
+        appear in `production` are treated as nodes that depend on the symbols in
+        their value list.
+    f_print : bool, optional
+        If True, print processing diagnostics (start symbols, joins) to stdout.
+        Default is False.
+
+    Returns
+    -------
+    rules : list of str
+        List of join rules in topologically valid order. Each rule is formatted
+        as ``"A + B = C"`` where ``A`` and ``B`` are the left-hand constituents and
+        ``C`` is the computed result string for the non-terminal.
+
+    Raises
+    ------
+    TypeError
+        If ``s`` is not a string or ``production`` is not a mapping-like object.
+    ValueError
+        If the dependency graph contains a cycle, the returned rules may be
+        incomplete; callers should validate acyclicity prior to calling if full
+        coverage is required.
+    """
+    in_degrees: Dict[str, int] = collections.defaultdict(int)
+    adj: Dict[str, List[str]] = collections.defaultdict(list)
+    tmap: Dict[str, str] = {}
+
+    # Initialize in-degrees and adjacency list
+    for c in s:
+        in_degrees[c] = 0
+    for course, prereqs in production.items():
+        for req in prereqs:
+            in_degrees[course] += 1
+            adj[req].append(course)
+
+    # Start queue with symbols having zero in-degrees
+    start_q: collections.deque[str] = collections.deque(
+        symbol for symbol, ins in in_degrees.items() if ins == 0
+    )
+    if f_print:
+        print(f"Processing {s}", flush=True)
+        print(f"Start symbols: {', '.join(start_q)}", flush=True)
+        print("Joins:", flush=True)
+
+    # Perform topological sort
+    rules: List[str] = []
+    while start_q:
+        symbol = start_q.popleft()
+        tmap[symbol] = symbol
+        for neighbor in adj[symbol]:
+            in_degrees[neighbor] -= 1
+            if in_degrees[neighbor] == 0:
+                start_q.append(neighbor)
+
+        if symbol in production:
+            if len(production[symbol]) == 2:
+                a, b = production[symbol]
+                tmap[symbol] = tmap[a] + tmap[b]
+                rules.append(f"{tmap[a]} + {tmap[b]} = {tmap[symbol]}")
+            else:
+                tmap[symbol] = production[symbol][0]
+
+    if f_print:
+        print("\n".join(rules), flush=True)
+
+    return rules
+
+
+def extract_virtual_objects(rules: List[str]) -> List[str]:
+    """
+    Extract virtual objects from a list of join rules, excluding the final rule's result.
+
+    Parameters
+    ----------
+    rules : list of str
+        Sequence of join rules formatted as ``"A + B = C"``. An empty sequence
+        results in an empty list.
+
+    Returns
+    -------
+    virt_objs : list of str
+        Sorted list of unique object identifiers found in the rules, excluding the
+        right-hand side (result) of the last rule. Sorting is by string length
+        (ascending).
+    """
+    if not rules:
+        return []
+
+    # Extract all objects from the rules
+    objects = {obj for rule in rules for obj in rule.replace(" + ", " = ").split(" = ")}
+
+    # Remove the last result
+    last_result = rules[-1].split(" = ")[-1]
+    objects.discard(last_result)
+
+    # Return the sorted list of objects by string length
+    return sorted(objects, key=len)
+
+
+def repair_with_pathways(s: Union[str, List[str]], f_print: bool = False, debug: bool = False) -> Tuple[
+    int, List[str], nx.DiGraph]:
+    """
+    Compute pathway information from an input string: path length, virtual objects, and a rules graph.
+
+    Performs grammar repair and CNF conversion via `ai_core`, derives join rules with `get_rules`,
+    extracts virtual objects with `extract_virtual_objects`, and builds a directed graph of rules
+    with `rules_to_graph`.
+
+    Parameters
+    ----------
+    s : Union[str, List[str]]
+        Input string or list of strings to be processed. Each character is treated as an initial terminal symbol.
+    f_print : bool, optional
+        If True, print join-rule processing diagnostics and the computed rules. Default is False.
+    debug : bool, optional
+        If True, enable debug printing in the underlying `ai_core` stage. Default is False.
+
+    Returns
+    -------
+    ai_count : int
+        Integer path-length metric returned by `ai_core` (heuristic count of introduced productions
+        and start-symbol length).
+    virt_obj : list of str
+        Sorted list of virtual object identifiers extracted from the join rules (excluding the final
+        rule result). Sorted by string length ascending.
+    rules_graph : networkx.DiGraph
+        Directed graph representing join relationships. For each join rule ``"A + B = C"`` there
+        are edges ``A -> C`` and ``B -> C``; virtual objects are added as isolated nodes when present.
+
+    Raises
+    ------
+    TypeError
+        If ``s`` is not a string. Underlying routines may raise additional errors for malformed
+        productions or rules.
+    """
+    # Get the production rules and path length
+    path_len, productions = ai_core(s, debug=debug)
+    # Get the rules
+    rules = get_rules(s, productions, f_print=f_print)
+    # Extract virtual objects
+    virt_obj = extract_virtual_objects(rules)
+    return path_len, virt_obj, rules_to_graph(rules, virt_obj)