polymerist.rdutils.reactions ============================ .. py:module:: polymerist.rdutils.reactions .. autoapi-nested-parse:: Utilities for representing and modelling chemical reactions between RDKit molecules Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/polymerist/rdutils/reactions/assembly/index /autoapi/polymerist/rdutils/reactions/fragment/index /autoapi/polymerist/rdutils/reactions/reactexc/index /autoapi/polymerist/rdutils/reactions/reactinfo/index /autoapi/polymerist/rdutils/reactions/reactions/index /autoapi/polymerist/rdutils/reactions/reactors/index Attributes ---------- .. autoapisummary:: polymerist.rdutils.reactions.IBIS Classes ------- .. autoapisummary:: polymerist.rdutils.reactions.AnnotatedReaction polymerist.rdutils.reactions.AtomTraceInfo polymerist.rdutils.reactions.BondTraceInfo polymerist.rdutils.reactions.BondChange polymerist.rdutils.reactions.IntermonomerBondIdentificationStrategy polymerist.rdutils.reactions.ReseparateRGroups polymerist.rdutils.reactions.CutMinimumCostBondsStrategy polymerist.rdutils.reactions.PolymerizationReactor polymerist.rdutils.reactions.ReactionAssembler Package Contents ---------------- .. py:class:: AnnotatedReaction(*args, **kwargs) Bases: :py:obj:`rdkit.Chem.rdChemReactions.ChemicalReaction` RDKit ChemicalReaction subclass with additional useful information about product atom and bond mappings and reaction naming Initialization must be done either via AnnotatedReaction.from_smarts, AnnotatedReaction.from_rdmols, or AnnotatedReaction.from_rxnfile .. py:attribute:: RXNNAME_LINE_NO :type: ClassVar[int] :value: 1 .. py:attribute:: RXNNAME_RE :type: ClassVar[re.Pattern] .. py:method:: from_smarts(rxn_smarts: str) -> AnnotatedReaction :classmethod: Instantiate reaction from mapped SMARTS string .. py:method:: to_smarts() -> str Export reaction as mapped SMARTS string .. py:property:: smarts :type: str Mapped SMARTS string representation of reaction .. py:method:: to_smiles() -> str Export reaction as mapped SMILES string .. py:property:: smiles :type: str Mapped SMILES string representation of reaction .. py:method:: from_rdmols(reactant_templates: Iterable[rdkit.Chem.rdchem.Mol], product_templates: Iterable[rdkit.Chem.rdchem.Mol], agent_templates: Optional[Iterable[rdkit.Chem.rdchem.Mol]] = None) -> AnnotatedReaction :classmethod: For instantiating reactions directly from molecules instead of SMARTS strings .. py:method:: rxnname_from_rxnfile(rxnfile_path: Union[str, pathlib.Path]) -> str :classmethod: Extract the reaction name from a (properly-formatted) .RXN file .. py:property:: rxnname :type: str A string handle associated with this reaction .. py:method:: from_rxnfile(rxnfile_path: Union[str, pathlib.Path]) -> AnnotatedReaction :classmethod: For instantiating reactions directly from MDL .rxn files .. py:method:: to_rxnfile(rxnfile_path: Union[str, pathlib.Path], wilds_to_R_groups: bool = True) -> None Save reaction to an MDL .RXN file. Replaces ports with R-groups to enable proper loading .. py:property:: mapped_atom_info_by_map_number :type: dict[int, polymerist.rdutils.reactions.reactinfo.AtomTraceInfo] Provenance info about the reactant origin and product destination of all mapped atoms, keyed by atom map numbers .. py:property:: mapped_atom_info :type: set[polymerist.rdutils.reactions.reactinfo.AtomTraceInfo] Compile provenance info about the reactant origin and product destination of all mapped atoms .. py:property:: mapped_atom_info_by_product_idx :type: dict[str, set[polymerist.rdutils.reactions.reactinfo.AtomTraceInfo]] Sets of provenance info about the reactant origin and product destination of all mapped atoms grouped by the indices of the products in which they appear .. py:property:: reactive_atom_info :type: dict[int, polymerist.rdutils.reactions.reactinfo.AtomTraceInfo] Compile reactant origin and product destination of all mapped atoms which are changed by the reaction .. py:property:: mapped_bond_info :type: set[polymerist.rdutils.reactions.reactinfo.BondTraceInfo] All provenance info on how bonds between mapped atoms (at least one of which is reactive) change over the reaction .. py:property:: mapped_bond_info_by_change_type :type: dict[Union[str, polymerist.rdutils.reactions.reactinfo.BondChange], set[polymerist.rdutils.reactions.reactinfo.BondTraceInfo]] Mapped bond provenance information, grouped by the types of bond changes each bond experienced .. py:property:: mapped_bond_info_by_product_idx :type: dict[Union[str, polymerist.rdutils.reactions.reactinfo.BondChange], set[polymerist.rdutils.reactions.reactinfo.BondTraceInfo]] Mapped bond provenance information, grouped by the index of the product the bond ends up in .. py:method:: compile_functional_group_inventory(labeled_reactants: dict[L, rdkit.Chem.rdchem.Mol]) -> polymerist.genutils.sequences.discernment.SymbolInventory[int, L] Construct an inventory of numbers of functional groups (reactant templates) found in an ordered pool of reactant Mols, which can be evaluated as a DISCERNMENT-type problem to determine valid reactant ordering(s), if some exist Isomorphisms to the DISCERNMENT problem in this instance are as follows: "symbols" <-> indices of functional groups, as-defined by reactant templates "target word" <-> the sequence of indices [n-1] = [0, 1, ..., n-1] where "n" is the number of reactant templates "magazine" <-> an ordered collection of reactant molecules, which may contain any number of functional groups apiece each "word labels" <-> the output of the provided labeling method on the reactant Mol or, if no labeling method is provided, the index of the reactant in the sequence .. py:method:: enumerate_valid_reactant_orderings(reactant_pool: Union[Iterable[rdkit.Chem.rdchem.Mol], Mapping[L, rdkit.Chem.rdchem.Mol]], labeling_method: Optional[Callable[[rdkit.Chem.rdchem.Mol], L]] = None, as_mols: bool = True, allow_resampling: bool = False, deterministic: bool = True) -> Generator[Union[None, tuple[L], tuple[rdkit.Chem.rdchem.Mol]], None, None] Enumerates all orderings of reactants compatible with the reactant templates defined in this reaction Yields: * a single NoneType if no such ordering exists * tuples of Chem.Mol objects if as_mols=True * tuples of molecule labels if as_mols=False. Labels can be: ** Indices of molecules in-sequence if labeling_method is not provided ** Any molecule label is labeling_method is provided; Note that the labels provided must be valid keys for indexing reactant_pool to support as_mols If allow_resampling=False, each reactant will only be allowed to contribute exactly 1 of its functional groups 1 to any solution .. py:method:: valid_reactant_ordering(reactant_pool: Sequence[rdkit.Chem.rdchem.Mol], as_mols: bool = True, allow_resampling: bool = False, deterministic: bool = True) -> Union[None, tuple[int], tuple[rdkit.Chem.rdchem.Mol]] Get first ordering of reactants compatible with the reactant templates defined in this reaction Yields: * a single NoneType if no such ordering exists * a tuple of Chem.Mol objects if as_mols=True * a tuple of indices of reactants in the passed sequence if as_mols=False If allow_resampling=False, each reactant will only be allowed to contribute exactly 1 of its functional groups 1 to any solution .. py:method:: has_reactable_subset(reactant_pool: Sequence[rdkit.Chem.rdchem.Mol], allow_resampling: bool = False) -> bool Determine if a sequence of reactants Mols contains any subset of Mols which are compatible with the reactant templates defined by this reaction If allow_resampling=False, each reactant will only be allowed to contribute exactly 1 of its functional groups 1 to any solution .. py:method:: validate_reactants(reactants: Sequence[rdkit.Chem.rdchem.Mol], allow_resampling: bool = False) -> None Check whether a collection of reactant Mols can be reacted with this reaction definition .. py:method:: reactants_are_compatible(reactants: Sequence[rdkit.Chem.rdchem.Mol], allow_resampling: bool = False) -> bool Determine whether a collection of reactants can be reacted with this reaction or not .. py:method:: apply_atom_info_to_product(product: rdkit.Chem.rdchem.Mol, product_atom_infos: Iterable[polymerist.rdutils.reactions.reactinfo.AtomTraceInfo], reactants: Sequence[rdkit.Chem.rdchem.Mol], apply_map_labels: bool = True) -> None :staticmethod: Transfer props and (if requested) map number information from atoms in reactant Mols to their corresponding atoms in a product Mol Acts in-place on the "product" Mol instance .. py:method:: apply_bond_info_to_product(product: rdkit.Chem.rdchem.Mol, product_bond_infos: Iterable[polymerist.rdutils.reactions.reactinfo.BondTraceInfo]) -> None :staticmethod: Mark any changed bonds with bond props and clean up bond type info in places where bonds get modified Acts in-place on the "product" Mol instance .. py:method:: react(reactants: Sequence[rdkit.Chem.rdchem.Mol], repetitions: int = 1, keep_map_labels: bool = True, _suppress_reactant_validation: bool = False) -> Generator[rdkit.Chem.rdchem.Mol, None, None] Execute reaction over a collection of reactants and generate product molecule(s) Does not require reactants to match the ORDER of the expected reactant templates by default (only to have the correct number of reactants) .. py:class:: AtomTraceInfo For encapsulating information about the origin and destination of a mapped atom, traced through a reaction .. py:attribute:: map_number :type: int .. py:attribute:: reactant_idx :type: int .. py:attribute:: reactant_atom_idx :type: int .. py:attribute:: product_idx :type: int .. py:attribute:: product_atom_idx :type: int .. py:class:: BondTraceInfo For encapsulating information about bonds which are between mapped atoms and which change during a reaction .. py:attribute:: map_nums :type: Union[tuple[int, int], frozenset[int]] .. py:attribute:: product_idx :type: Optional[int] .. py:attribute:: product_bond_idx :type: Optional[int] .. py:attribute:: bond_change_type :type: Union[str, BondChange] .. py:attribute:: initial_bond_type :type: Union[float, rdkit.Chem.BondType] .. py:attribute:: final_bond_type :type: Union[float, rdkit.Chem.BondType] .. py:class:: BondChange Bases: :py:obj:`enum.StrEnum` For indicating how a bond which changed in a reaction was altered .. py:attribute:: ADDED .. py:attribute:: DELETED .. py:attribute:: MODIFIED .. py:attribute:: UNCHANGED .. py:data:: IBIS .. py:class:: IntermonomerBondIdentificationStrategy Bases: :py:obj:`abc.ABC` Abstract base for Intermonomer Bond Identification Strategies for fragmentation during in-silico polymerization .. py:method:: locate_intermonomer_bonds(product: rdkit.Chem.Mol) -> Generator[int, None, None] Generates the indices of all identified inter-monomer bonds by molecule, no more than once each .. py:method:: produce_fragments(product: rdkit.Chem.Mol, separate: bool = True) -> Union[rdkit.Chem.Mol, tuple[rdkit.Chem.Mol]] Apply break all bonds identified by this IBIS algorithm and return the resulting fragments .. py:class:: ReseparateRGroups Bases: :py:obj:`IntermonomerBondIdentificationStrategy` IBIS which cleaves any new bonds formed between atoms that were formerly the start of an R-group in the reaction template .. py:class:: CutMinimumCostBondsStrategy(base_bond_cost: Optional[float] = None, bond_discounts: Optional[dict[str, tuple[int, Callable[[rdkit.Chem.Mol], tuple[int, int]]]]] = None, bond_cost_keyword: Optional[str] = 'cost_to_cut', max_bonds_per_cut: int = 1, *args: P, **kwargs: P) Bases: :py:obj:`IntermonomerBondIdentificationStrategy` Subtype of IBIS which chooses bonds as solutions to minimum graph cut problem All bonds in a molecule are given some base cost to cut, then a discount is applied to some bonds by specified conditions Cuts are then made (no more than once) on the lowest cost bond(s) separating each pair of R-groups .. py:attribute:: base_bond_cost :value: None .. py:attribute:: bond_discounts :value: None .. py:attribute:: bond_cost_keyword :value: 'cost_to_cut' .. py:attribute:: max_bonds_per_cut :value: 1 .. py:class:: PolymerizationReactor Reactor which exhaustively generates monomers fragments according to a given a polymerization mechanism .. py:attribute:: rxn_schema :type: polymerist.rdutils.reactions.reactions.AnnotatedReaction .. py:attribute:: fragment_strategy :type: polymerist.rdutils.reactions.fragment.IBIS .. py:method:: propagate_pooled(monomers: Iterable[rdkit.Chem.rdchem.Mol], rxn_depth_max: int = 5, allow_resampling: bool = False, clear_map_labels: bool = True, clear_dummy_labels: bool = False, sanitize_ops: rdkit.Chem.rdmolops.SanitizeFlags = SANITIZE_ALL, aromaticity_model: rdkit.Chem.rdmolops.AromaticityModel = AROMATICITY_MDL) -> dict[polymerist.smileslib.cleanup.Smiles, rdkit.Chem.rdchem.Mol] Discovers and enumerates all possible repeat unit fragments formable from a given polymerization step reaction mechanism Propagation acts on a pool of fragments reactants (initially just the "monomers" passed in) and proceeds in rounds where all reactible subsets are adducted and fragmented, and any previously-unseen fragments are added to the pool Enumeration halts either when no new fragments have been found or the set maximum number of reaction step(s) is reached "Uniqueness" of a fragment is assessed by its RDKit-canonicalized SMILES representation .. py:method:: propagate(monomers: Sequence[rdkit.Chem.rdchem.Mol], clear_map_labels: bool = True, sanitize_ops: rdkit.Chem.rdmolops.SanitizeFlags = SANITIZE_ALL, aromaticity_model: rdkit.Chem.rdmolops.AromaticityModel = AROMATICITY_MDL) -> Generator[tuple[tuple[rdkit.Chem.rdchem.Mol, Ellipsis], tuple[rdkit.Chem.rdchem.Mol, Ellipsis]], None, None] Keep reacting and fragmenting a pair of monomers until all reactive sites have been reacted Returns fragment pairs at each step of the chain propagation process .. py:class:: ReactionAssembler Class for producing reaction templates from reactants, bond derangements .. py:attribute:: reactive_groups :type: Iterable[rdkit.Chem.rdchem.Mol] .. py:attribute:: byproducts :type: Iterable[rdkit.Chem.rdchem.Mol] :value: [] .. py:attribute:: bond_derangement :type: dict[int, tuple[int, int]] .. py:attribute:: rxn_name :type: str :value: '' .. py:property:: reactants :type: rdkit.Chem.rdchem.RWMol Combine cached reactive groups into single, contiguously-numbered Mol for manipulation .. py:method:: products(show_steps: bool = False, sanitize_ops: rdkit.Chem.rdmolops.SanitizeFlags = SANITIZE_ALL, bond_breakage_marker: str = '--x->', bond_formation_marker: str = '---->') -> rdkit.Chem.rdchem.Mol Generate the product template defined by the provided reactants and bond derangement .. py:method:: products_by_importance(combined: bool = True, show_steps: bool = False, sanitize_ops: rdkit.Chem.rdmolops.SanitizeFlags = SANITIZE_ALL) -> tuple[Union[Optional[rdkit.Chem.rdchem.Mol], list[rdkit.Chem.rdchem.Mol]], Union[Optional[rdkit.Chem.rdchem.Mol], list[rdkit.Chem.rdchem.Mol]]] Partition reaction products into major and minor/byproducts, each returned as a single Combined Mol .. py:property:: byproduct_map_nums :type: tuple[set, set] Partitions map numbers present in the product(s) by whether or not they belong to a collection of side products Returns a set of map numbers NOT in a side product and set set which are .. py:property:: byproduct_relabeling :type: dict[int, int] Determine a relabeling of the N map numbers in the reaction template which are not any of the given side products Relabeling is in standard form, i.e. new labels are taken from the first N natural numbers with the order of labels preserved .. py:method:: assemble_rxn(show_steps: bool = False, sanitize_ops: rdkit.Chem.rdmolops.SanitizeFlags = SANITIZE_ALL) -> polymerist.rdutils.reactions.reactions.AnnotatedReaction Assemble MDL rxn template from information stored in self