dynordg 0.1.2__tar.gz

dynordg-0.1.2/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+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.

dynordg-0.1.2/MANIFEST.in

@@ -0,0 +1 @@
+include dynordg/data/*.csv

dynordg-0.1.2/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: dynordg
+Version: 0.1.2
+Summary: Simulate and render the flux of Ribosomes through Ribosomal Phase Space
+Author-email: "Kyle A. Meiklejohn" <kyle.meiklejohn314@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/k-meiklejohn/dynordg
+Project-URL: Issues, https://github.com/k-meiklejohn/dynordg/issues
+Keywords: translation,ribosome decision graph,RDG,simulation,graph
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: biopython>=1.86
+Requires-Dist: levenshtein>=0.27.3
+Requires-Dist: matplotlib>=3.10.6
+Requires-Dist: networkx>=3.5
+Requires-Dist: pandas>=2.3.3
+Dynamic: license-file
+
+# DYNORDG
+
+Dynamic Ribosome Decision Graphs (RDGs) for simulating and visualizing ribosome flux along transcripts.
+
+## Overview
+
+A Ribosome Decision Graph (RDG) models the possible paths a ribosome can take along an mRNA transcript.
+
+**Dynamic RDGs** extend this by:
+- Representing ribosome flux using edge thickness
+- Implicitly encoding overlapping translons via flow rather than explicit separation
+- Modeling ribosomal phase states based on downstream potential
+
+This package provides tools to:
+- Build RDGs from transcript sequences, or from user defined phase transistions
+- Simulate ribosome movement
+- Render dynamic flux graphs
+
+## Installation
+
+```bash
+pip install dynordg
+```
+
+## Quick Start
+
+```python
+from dynordg import Transcript, RiboGraphFlux, RiboGraphVis
+
+# Create transcript
+t = Transcript("AUGGCCAUGGCGCCCAGAACUGGGUAA")
+
+# Automatically detect start/stop events
+t.auto_stop_starts()
+
+# Build flux graph
+graph = RiboGraphFlux(t.transition_map)
+
+# Create render object
+plot = RiboGraphVis(graph)
+
+# Render
+plot.show()
+```
+
+## Example Output
+
+Below is example dynamic RDG (if not a realistic one):
+
+![Example RDG](docs/example.png)
+
+
+
+

dynordg-0.1.2/README.md

@@ -0,0 +1,54 @@
+# DYNORDG
+
+Dynamic Ribosome Decision Graphs (RDGs) for simulating and visualizing ribosome flux along transcripts.
+
+## Overview
+
+A Ribosome Decision Graph (RDG) models the possible paths a ribosome can take along an mRNA transcript.
+
+**Dynamic RDGs** extend this by:
+- Representing ribosome flux using edge thickness
+- Implicitly encoding overlapping translons via flow rather than explicit separation
+- Modeling ribosomal phase states based on downstream potential
+
+This package provides tools to:
+- Build RDGs from transcript sequences, or from user defined phase transistions
+- Simulate ribosome movement
+- Render dynamic flux graphs
+
+## Installation
+
+```bash
+pip install dynordg
+```
+
+## Quick Start
+
+```python
+from dynordg import Transcript, RiboGraphFlux, RiboGraphVis
+
+# Create transcript
+t = Transcript("AUGGCCAUGGCGCCCAGAACUGGGUAA")
+
+# Automatically detect start/stop events
+t.auto_stop_starts()
+
+# Build flux graph
+graph = RiboGraphFlux(t.transition_map)
+
+# Create render object
+plot = RiboGraphVis(graph)
+
+# Render
+plot.show()
+```
+
+## Example Output
+
+Below is example dynamic RDG (if not a realistic one):
+
+![Example RDG](docs/example.png)
+
+
+
+

dynordg-0.1.2/pyproject.toml

@@ -0,0 +1,40 @@
+# pyproject.toml
+
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dynordg"
+version = "0.1.2"
+description = "Simulate and render the flux of Ribosomes through Ribosomal Phase Space"
+readme = "README.md"
+authors = [{name = "Kyle A. Meiklejohn", email="kyle.meiklejohn314@gmail.com"}]
+license = 'MIT'
+license-files = ["LICEN[CS]E*"]
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+
+
+keywords = ["translation", "ribosome decision graph", "RDG", "simulation", "graph"]
+
+dependencies = [
+    "biopython >=1.86",
+    "levenshtein >= 0.27.3",
+    "matplotlib >= 3.10.6",
+    "networkx >= 3.5",
+    "pandas >= 2.3.3",
+]
+
+requires-python = ">=3.12"
+
+[project.urls]
+Homepage = "https://github.com/k-meiklejohn/dynordg"
+Issues = "https://github.com/k-meiklejohn/dynordg/issues"
+
+[tool.setuptools.package-data]
+"dynordg" = ['data/*.csv']

dynordg-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dynordg-0.1.2/src/dynordg/__init__.py

@@ -0,0 +1,2 @@
+from .classes import RiboNode, RiboEvent, RiboGraph, RiboTransition, TransitionMap, RiboGraphFlux, RiboGraphVis, Transcript
+from .functions import start_score

dynordg-0.1.2/src/dynordg/classes/__init__.py

@@ -0,0 +1,5 @@
+from .core import RiboEvent, RiboNode, RiboTransition
+from .graph import RiboGraph
+from .simulation import RiboGraphFlux, Transcript, TransitionMap
+from .viz import RiboGraphVis
+from ..data import AUG_SCORE, NON_AUG_SCORE

dynordg-0.1.2/src/dynordg/classes/core/__init__.py

@@ -0,0 +1,3 @@
+from .nodes import RiboNode
+from .transitions import RiboTransition
+from .events import RiboEvent

dynordg-0.1.2/src/dynordg/classes/core/events.py

@@ -0,0 +1,147 @@
+from .nodes import RiboNode
+from .transitions import RiboTransition
+import re
+
+class RiboEvent(tuple):
+    """
+    Tuple in the form position:int, type: str, probability: float, drop_probability: float
+    Probabilities must be 0 <= p <= 1 and must not add to be greater than 1 (except termination which \
+    may have a probability (of reinitiation) and a drop_probability).
+    """
+
+
+    def _initiation_transition(self):
+        transitions = []
+        if self.probability > 0:
+            transitions.append(RiboTransition(RiboNode(self.position, 0), 
+                                              RiboNode(self.position, self.frame), 
+                                              self.probability))
+        if self.drop_probability > 0:
+            transitions.append(self.bulk_transition(0))
+        return transitions
+    
+    def _termination_transition(self):
+        transitions = []
+        if self.probability > 0:
+            transitions.append(RiboTransition(RiboNode(self.position, self.frame), 
+                                              RiboNode(self.position, 0), 
+                                              self.probability))
+        if self.drop_probability > 0:
+            transitions.append(self.bulk_transition(self.frame))
+
+        return transitions
+    
+    def _frameshift_transition(self):
+        transitions = []
+        shift_to_pos = self.position + self.shift
+        shift_to_frame = shift_to_pos % 3 + 1
+        if self.probability > 0:
+            transitions.append(RiboTransition(RiboNode(self.position, self.frame),
+                                               RiboNode(shift_to_pos, shift_to_frame ), 
+                                               self.probability))
+        if self.drop_probability > 0:
+            transitions.append(self.bulk_transition(self.frame))
+        return transitions
+    
+    def _ires_transition(self):
+        transitions = []
+        if self.probability > 0:
+            transitions.append(RiboTransition(RiboNode(self.position, -1), 
+                                            RiboNode(self.position, self.frame), 
+                                            self.probability))
+        return transitions
+
+    def _cap_transition(self):
+        transitions = []
+        if self.probability > 0:
+            transitions.append(RiboTransition(RiboNode(self.position, -1), 
+                                            RiboNode(self.position, 0), 
+                                            self.probability))
+        return transitions
+    
+
+    def _end_transition(self):
+        transitions = []
+        if self.drop_probability > 0:
+            for phase in range(4):
+                transitions.append(self.bulk_transition(phase))
+        return transitions
+
+
+    TRANSITION_MAP = {
+        'initiation':  _initiation_transition,
+        'termination':    _termination_transition,
+        'frameshift+1': _frameshift_transition,
+        'frameshift-1': _frameshift_transition,
+        'ires':  _ires_transition,
+        'cap': _cap_transition,
+        'end': _end_transition
+    }
+
+
+    def bulk_transition(self, phase):
+        return RiboTransition(RiboNode(self.position, phase), RiboNode(self.position, -1), self.drop_probability)
+
+
+    @property
+    def frame(self):
+        """
+        Provides the frame (1,2,3) of the event
+        """
+        return (self.position % 3) + 1
+    
+    
+
+    @property
+    def shift(self):
+        """
+        If event is a frameshift type, this gives the direction and magnitude of the frameshift
+        """
+        match = re.search(r'shift([+-]?\d+)', self.type)
+        return int(match.group(1)) if match else 0
+
+    def __new__(cls, *args):
+            
+            if len(args) == 1 and isinstance(args[0], (tuple, RiboEvent)):
+                data = args[0]
+            elif len(args) == 4:
+                data = args
+            else:
+                raise ValueError(f'RiboEvent requires either or a length-4 tuple, got: {args}')
+
+            if len(data) != 4:
+                raise ValueError(f'RiboEvent tuple must be of length 4, got length: {len(data)}')
+            
+
+            if not isinstance(data[0], int):
+                raise ValueError(f"Position of RiboEvent tuple must be 'int', got {type(data[0]).__name__!r}")
+            elif not isinstance(data[1], str):
+                raise ValueError(f"Type of RiboEvent tuple must be 'str', got {type(data[1]).__name__!r}")
+            elif not all(isinstance(x, (float, int)) for x in data[2:]):
+                raise ValueError("Probabilities must be float or int")
+            elif all(x == 0 for x in data[2:]):
+                raise ValueError(f'At least one probability must be non-zero')
+            if not data[1] in ('cap', 'ires', 'termination'):
+                if sum(data[2:]) > 1:
+                    raise ValueError(f"Sum of Probabilities for non-loading ('cap', 'ires') RiboEvent cannot exceed 1 or be 0, got {sum(data[2:])}")
+
+            return super().__new__(cls, data)
+    
+    def __init__(self, *args):
+        super().__init__()
+        self.position = self[0]
+        self.type = self[1]
+        self.probability = self[2]
+        self.drop_probability = self[3]
+
+    def __repr__(self):
+        return f"(Pos:{self.position}, type:{self.type}, prob:{self.probability}, drop:{self.drop_probability})"
+    
+    def to_transition(self) -> list[RiboTransition]:
+        """
+        Returns a list of RiboTransitions coresponding to the event
+        """
+        handler = self.TRANSITION_MAP.get(self.type)
+        if handler is None:
+            raise ValueError(f"No transition defined for event type {self.type!r}")
+        return handler(self)

dynordg-0.1.2/src/dynordg/classes/core/nodes.py

@@ -0,0 +1,45 @@
+class RiboNode(tuple):
+    """
+    Special 2-tuple that refers to a position in simplified Ribosomal phase space, the first integer \
+    refers to the nucleotide position on a transcript, while the second refers to the phase \
+    of the ribosome: -1 for not associated, 0 for scanning and 1,2,3 for translating in the frame \
+    where frame = position % 3 + 1
+    
+    """
+    def __new__(cls, *args):
+        if len(args) == 1 and isinstance(args[0], (tuple, RiboNode)):
+            coords = args[0]
+        elif len(args) == 2:
+            coords = args
+        else:
+            raise ValueError(f'RiboNode requires 2 ints or a length-2 tuple, got: {args}')
+
+        if len(coords) != 2:
+            raise ValueError(f'RiboNode tuple must be of length 2, got length: {len(coords)}')
+
+        x, y = coords
+
+        if not isinstance(x, int) or not isinstance(y, int):
+            raise ValueError("RiboNode coordinates must be ints")
+
+        if not (-1 <= y < 4):
+            raise ValueError("position must be between -1 and 3")
+
+        return super().__new__(cls, (x, y))
+
+    @property
+    def position(self) -> int:
+        """
+        Nucleotide position of the node
+        """
+        return self[0]
+
+    @property
+    def phase(self) -> int:
+        """
+        Simplified phase of the node -1 is not reading, 0 is scanning, 1, 2, 3 are translating in one of those frames
+        """
+        return self[1]
+
+    def __repr__(self):
+        return f"(Pos:{self.position}, Phase:{self.phase})"

dynordg-0.1.2/src/dynordg/classes/core/transitions.py

@@ -0,0 +1,49 @@
+from .nodes import RiboNode
+
+class RiboTransition(tuple):
+    """
+    A RiboTransition is an edge of a graph that shows a possible transition between phases, \
+    it consists of a initial position in ribosomal phase space, (source, RiboNode), a terminal position (target, RiboNode), \
+    and the probability that a ribosome reaching the source position will choose that path.
+    """
+    
+    def __new__(cls, *args):
+        if len(args) == 1 and isinstance(args[0], (tuple, RiboTransition)):
+            data = args[0]
+        elif len(args) == 3:
+            data = args
+        else:
+            raise ValueError(f'RiboTransition requires either 3 arguments or a length-3 tuple, got: {args}')
+
+        if len(data) != 3:
+            raise ValueError(f'RiboTransition must be of length 3, got length: {len(data)}')
+
+        source, target, prob = data
+
+        # Coerce RiboNode-like tuples
+        if not isinstance(source, RiboNode):
+            if isinstance(source, tuple):
+                source = RiboNode(source)
+            else:
+                raise TypeError(f"Source must be 'RiboNode' or RiboNode-like tuple, got {type(source).__name__!r}")
+        if not isinstance(target, RiboNode):
+            if isinstance(target, tuple):
+                target = RiboNode(target)
+            else:
+                raise TypeError(f"Target must be 'RiboNode' or RiboNode-like tuple, got {type(target).__name__!r}")
+
+        if not isinstance(prob, (int, float)):
+            raise TypeError(f"Probability must be 'float' or 'int', got {type(prob).__name__!r}")
+        if not 0 < prob <= 1 and source.phase != -1:
+            raise ValueError(f"Probability must be in range (0, 1], got {prob}")
+
+        return super().__new__(cls, (source, target, prob))
+
+    def __init__(self, *args):
+        super().__init__()
+        self.source = self[0]
+        self.target = self[1]
+        self.probability = self[2]
+
+    def __repr__(self):
+        return f"(Source:{self.source}, Target:{self.target}, Probability:{self.probability})"

dynordg-0.1.2/src/dynordg/classes/graph/__init__.py

@@ -0,0 +1 @@
+from .ribograph import RiboGraph

dynordg-0.1.2/src/dynordg/classes/graph/ribograph.py

@@ -0,0 +1,93 @@
+from ..core import  RiboNode
+from networkx import DiGraph
+
+class RiboGraph(DiGraph):
+    """
+    A NetworkX Digraph that only accepts RiboNode instances as nodes
+    """
+
+    def __init__(self, incoming_graph_data = None, **attr):
+        super().__init__(incoming_graph_data, **attr)
+        self.bulk_node = RiboNode((-1,-1))
+        self.add_node(self.bulk_node)
+
+    def add_node(self, node_for_adding: RiboNode, **attr):
+        """
+        Add a new RiboNode to the graph
+        """
+        if isinstance(node_for_adding, RiboNode):
+            pass
+        elif isinstance(node_for_adding, tuple):
+            node_for_adding = RiboNode(node_for_adding)
+        else:
+            raise TypeError(f"Ribograph only accepts RiboNodes or RiboNode-like tuples, got {type(node_for_adding).__name__!r}")
+        super().add_node(node_for_adding, **attr)
+    
+    
+    def add_nodes_from(self, nodes_for_adding, **attr):
+        """
+        Add multiple RiboNodes to a graph
+        """
+        for node in nodes_for_adding:
+            n = node[0] if isinstance(node, tuple) else node
+            if not isinstance(n, RiboNode):
+                if isinstance(n, tuple):
+                    pass  # will be coerced by add_node
+                else:
+                    raise TypeError(f'RiboGraph only accepts RiboNodes or RiboNode-like tuples, got {type(n).__name__!r}')
+        super().add_nodes_from(nodes_for_adding, **attr)
+    
+    
+    def add_edge(self, u, v, **attr):
+        """
+        Add an edge consisting of 2 RiboNodes to a graph
+        """
+        if not isinstance(u, RiboNode):
+            u = RiboNode(u)
+        if not isinstance(v, RiboNode):
+            v = RiboNode(v)
+
+        if self.has_edge(u, v):
+            existing = self.edges[u, v]
+            merged = {}
+            for key in set(existing) | set(attr):
+                existing_val = existing.get(key)
+                new_val = attr.get(key)
+                if existing_val is None:
+                    merged[key] = new_val
+                elif new_val is None:
+                    merged[key] = existing_val
+                elif key.startswith('flux'): #this may change
+                    merged[key] = existing_val + new_val
+                else:
+                    merged[key] = new_val  # overwrite non-flux attributes
+            super().add_edge(u, v, **merged)
+        else:
+            super().add_edge(u, v, **attr)
+
+    def horizontal_in_edge(self, node: RiboNode, data:bool|str|list=False):
+        """
+        Returns the in edge in the same phase as the node
+        """
+        if data:
+            for u, v, data in self.in_edges(node, data=data):
+                if u.phase == node.phase:
+                    return (u,v,data)
+        else:    
+            for u, v in self.in_edges(node):
+                if u.phase == node.phase:
+                    return (u,v)
+    def horizontal_out_edge(self, node: RiboNode, data:bool|str|list=False):
+        """
+        Returns the out edge in the same phase as the node
+        """
+
+        if data:
+            for u, v, data in self.out_edges(node, data=data):
+                if v.phase == node.phase:
+                    return (u,v, data)
+            
+        else:    
+            for u, v in self.in_edges(node):
+                if u.phase == node.phase:
+                    return (u,v)

dynordg-0.1.2/src/dynordg/classes/simulation/__init__.py

@@ -0,0 +1,3 @@
+from .fluxgraph import RiboGraphFlux
+from .transitionmap import TransitionMap
+from .transcript import Transcript