nuc2d 0.1.2__py3-none-any.whl

nuc2d/__init__.py

@@ -0,0 +1,5 @@
+from .draw import draw_svg
+
+__all__ = [
+    "draw_svg",
+]

nuc2d/annotation.py

@@ -0,0 +1,78 @@
+"""Utilities for attaching annotations to RNA secondary structures.
+
+This module provides functions for adding biological or visualization-
+related annotations to parsed secondary structure objects. Examples
+include nucleotide sequences, base-pair probabilities, and other
+metadata associated with nucleotides or structural elements.
+
+Annotations are applied after parsing and before layout or rendering,
+allowing structural topology and auxiliary information to remain
+separated.
+"""
+
+import numpy as np
+
+from .structure import (
+    StemRegion,
+    LoopRegion,
+)
+
+def attach_sequences(root_loop: LoopRegion, sequences: list[str]):
+    """Attach nucleotide sequences to a secondary structure.
+
+    Parameters
+    ----------
+    root_loop : LoopRegion
+        Root loop of the secondary structure.
+    sequences : list[str]
+        Nucleotide sequences for all strands.
+    """
+    def _attach_stem_sequences(current_stem: StemRegion):
+        for nt in current_stem.nucleotides[1:-1]:
+            nt.base = sequences[nt.strand_index][nt.index_in_strand]
+        _attach_loop_sequences(current_stem.child_loop)
+    
+    def _attach_loop_sequences(current_loop: LoopRegion):
+        if current_loop.is_root:
+            nucleotides = current_loop.nucleotides
+        else:
+            nucleotides = current_loop.nucleotides[1:-1]
+        for nt in nucleotides:
+            nt.base = sequences[nt.strand_index][nt.index_in_strand]
+        for stem in current_loop.child_stems:
+            _attach_stem_sequences(stem)
+    
+    _attach_loop_sequences(root_loop)
+
+def attach_basepair_probabilities(root_loop: LoopRegion, probs: np.ndarray):
+    """Attach base-pair probabilities to a secondary structure.
+
+    Parameters
+    ----------
+    root_loop : LoopRegion
+        Root loop of the secondary structure.
+    probs : ndarray
+        Base-pair probability matrix. Element (i, j) gives the probability
+        that nucleotide i pairs with nucleotide j. Diagonal elements give
+        the probabilities that nucleotides remain unpaired.
+    """
+    def _attach_stem_probs(current_stem: StemRegion):
+        nucleotides = current_stem.nucleotides
+        for idx in range(len(nucleotides)//2):
+            nt1 = nucleotides[idx]
+            nt2 = nucleotides[-(idx+1)]
+            prob = probs[nt1.index][nt2.index]
+            nt1.basepair_probability = nt2.basepair_probability = prob
+        _attach_loop_probs(current_stem.child_loop)
+    
+    def _attach_loop_probs(current_loop: LoopRegion):
+        if current_loop.is_root:
+            nucleotides = current_loop.nucleotides
+        else:
+            nucleotides = current_loop.nucleotides[1:-1]
+        for nt in nucleotides:
+            nt.basepair_probability = probs[nt.index][nt.index]
+        for stem in current_loop.child_stems:
+            _attach_stem_probs(stem)
+    
+    _attach_loop_probs(root_loop)

nuc2d/draw.py

@@ -0,0 +1,106 @@
+"""High-level drawing interface for nucleic acid secondary structures.
+
+This module provides convenience functions for generating SVG drawings
+directly from secondary structure strings. Parsing, annotation,
+layout generation, and rendering are performed automatically.
+"""
+
+from typing import Optional
+
+import numpy as np
+import svgwrite
+
+from .parser import parse
+from .annotation import (
+    attach_sequences,
+    attach_basepair_probabilities,
+)
+from .layout import RadialLayoutEngine
+from .style import DrawingStyle
+from .svg import (
+    PlacedComponent,
+    render_structure,
+    render_colorbar,
+    compose,
+)
+
+
+def draw_svg(
+    dpp_string: str,
+    sequences: Optional[list[str]] = None,
+    probs: Optional[np.ndarray] = None,
+    style: Optional[DrawingStyle] = None,
+    target_height: float = 500.0,
+) -> svgwrite.Drawing:
+    """Generate an SVG drawing from a secondary structure string.
+
+    Parameters
+    ----------
+    dpp_string : str
+        A secondary structure written in dot-parens-plus notation.
+    sequences : list[str], optional
+        A list of sequences corresponding to the structure.
+    probs : ndarray, optional
+        Base-pair probability matrix.
+    style : DrawingStyle, optional
+        Drawing style configuration.
+    target_height : float, default=500.0
+        Target height of the rendered secondary structure in the SVG
+        coordinate system.
+
+    Returns
+    -------
+    svgwrite.Drawing
+        Generated SVG drawing.
+    """
+    # Parse the secondary structure string.
+    root_loop = parse(dpp_string)
+
+    # Attach sequence and probability annotations.
+    if sequences is not None:
+        attach_sequences(root_loop, sequences)
+    if probs is not None:
+        attach_basepair_probabilities(root_loop, probs)
+
+    # Compute nucleotide positions and drawing geometry.
+    layout_result = RadialLayoutEngine().layout(root_loop)
+
+    # Create an empty SVG drawing that will hold all rendered components.
+    svg_drawing = svgwrite.Drawing()
+
+    # Render the RNA secondary structure as an independent SVG component.
+    structure = render_structure(
+        svg_drawing,
+        layout_result,
+        style,
+    )
+    placed_components = [
+        PlacedComponent(
+            component=structure,
+            x=0.0,
+            y=0.0,
+            scale=target_height / structure.height,
+        )
+    ]
+
+    # Add a colorbar when base-pair probabilities are visualized.
+    if probs is not None:
+        colorbar = render_colorbar(
+            svg_drawing,
+            style=style,
+        )
+        placed_components.append(
+            PlacedComponent(
+                component=colorbar,
+                x=placed_components[0].width,
+                y=0.0,
+                scale=target_height / colorbar.height,
+            )
+        )
+
+    # Compose all positioned components into the final SVG drawing.
+    compose(
+        svg_drawing,
+        placed_components,
+    )
+    return svg_drawing

nuc2d/layout.py

@@ -0,0 +1,321 @@
+"""Geometry layout generation for secondary structure visualization.
+
+This module converts secondary structure representations into drawable
+geometric layouts. The generated layouts define spatial relationships
+between nucleotides, stems, loops, and their connections, independently
+from rendering.
+
+The layout result typically consists of layout nodes and edges annotated
+with geometric information such as positions, orientations, and edge
+shapes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+from abc import ABC, abstractmethod
+import math
+
+from .structure import Nucleotide, LoopRegion, StemRegion
+from .vec2 import Vec2
+
+class EdgeType(Enum):
+    """Enumeration of edge types used in the drawing graph."""
+    BACKBONE = auto()
+    BASE_PAIR = auto()
+
+
+@dataclass
+class Node:
+    """Node representing a nucleotide and its drawing position.
+
+    Attributes
+    ----------
+    nucleotide : Nucleotide
+        Nucleotide associated with this node.
+    pos : Vec2
+        Position of the node in the drawing coordinate system.
+    """
+    nucleotide: Nucleotide
+    pos: Vec2
+
+
+@dataclass
+class Edge:
+    """Base class representing a connection between two nodes.
+
+    Attributes
+    ----------
+    start : Node
+        Start node of the edge.
+    end : Node
+        End node of the edge.
+    type : EdgeType
+        Type of the edge.
+    """
+    start: Node
+    end: Node
+    type: EdgeType
+
+
+@dataclass
+class LineEdge(Edge):
+    """Edge represented as a straight line segment."""
+    pass
+
+
+@dataclass
+class ArcEdge(Edge):
+    """Edge represented as an SVG elliptical arc.
+
+    Attributes
+    ----------
+    rx : float
+        Radius of the ellipse along the x-axis.
+    ry : float
+        Radius of the ellipse along the y-axis.
+    x_axis_rotation : float
+        Rotation angle of the ellipse x-axis in degrees.
+    large_arc : bool
+        Whether to use the larger arc between the endpoints.
+    sweep : bool
+        Direction of the arc sweep.
+    """
+    rx: float
+    ry: float
+    x_axis_rotation: float
+    large_arc: bool
+    sweep: bool
+
+@dataclass
+class Marker():
+    node: Node
+
+@dataclass
+class ArrowMarker(Marker):
+    direction: Vec2
+    length: float = 7.0
+    is_start: bool = True
+
+@dataclass
+class LayoutResult():
+    """Container for the generated layout information.
+
+    Attributes
+    ----------
+    nodes : list[Node]
+        Nodes with computed layout positions.
+    edges : list[Edge]
+        Edges connecting the laid out nodes.
+    markers : list[Marker]
+        Markers associated with the layout, such as directional annotations.
+    """
+    nodes: list[Node]
+    edges: list[Edge]
+    markers: list[Marker]
+
+class LayoutEngine(ABC):
+    """Abstract base class for secondary structure layout engines."""
+
+    @abstractmethod
+    def layout(self, root_loop: LoopRegion):
+        """Compute a layout for the given secondary structure."""
+        pass
+
+class RadialLayoutEngine(LayoutEngine):
+    """Layout engine for generating a radial representation of a secondary structure.
+    
+    This layout engine places nucleotides and structural elements using a
+    radial geometry based on backbone lengths, base-pair lengths, and
+    deflection angles between connected regions.
+    
+    Parameters
+    ----------
+    backbone_length : float, default=15
+        Length assigned to backbone connections between adjacent nucleotides.
+    basepair_length : float, default=20
+        Length assigned to base-pair connections in stem regions.
+    deflection_angle : float, default=math.pi/18
+        Angular deflection applied when traversing connected regions.
+    
+    Attributes
+    ----------
+    backbone_length : float
+        Length assigned to backbone connections.
+    basepair_length : float
+        Length assigned to base-pair connections.
+    deflection_angle : float
+        Angular deflection between connected regions.
+    nodes : list[Node]
+        Layout nodes generated during layout computation.
+    edges : list[Edge]
+        Layout edges generated during layout computation.
+    current_pos : Vec2
+        Current position used during recursive layout generation.
+    current_vec : Vec2
+        Current unit direction vector used during recursive layout generation.
+    """
+
+    def __init__(
+        self,
+        backbone_length: float = 15,
+        basepair_length: float = 20,
+        deflection_angle: float = math.pi/18,
+    ) -> None:
+        self.backbone_length = backbone_length
+        self.basepair_length = basepair_length
+        self.deflection_angle = deflection_angle
+        self.nodes: list[Node] = []
+        self.edges: list[Edge] = []
+        self.markers: list[Marker] = []
+        self.current_pos: Vec2 = Vec2(0, 0)
+        self.current_vec: Vec2 = Vec2(1, 0)
+    
+    def add_last_stem_backbone(self):
+        if not self.nodes[-2].nucleotide.is_three_prime:
+            self.edges.append(LineEdge(self.nodes[-2], self.nodes[-1], EdgeType.BACKBONE))
+    
+    def add_last_loop_backbone(self, radius: float):
+        if not self.nodes[-2].nucleotide.is_three_prime:
+            self.edges.append(ArcEdge(self.nodes[-2], self.nodes[-1], EdgeType.BACKBONE, radius, radius, 0, 0, 1))
+
+    def layout_stem(
+        self,
+        current_stem: StemRegion,
+    ) -> None:
+        """Generate layout information for a stem region.
+
+        Parameters
+        ----------
+        current_stem : StemRegion
+            Stem region to layout.
+        """
+        self.current_vec = self.current_vec.normalized()
+        stem_length = len(current_stem.nucleotides)//2
+        start_node = self.nodes[-1]
+        for start_idx in [0, stem_length]:
+            nucleotides = current_stem.nucleotides[start_idx+1:start_idx+stem_length]
+            for nt in nucleotides:
+                # Generate nodes
+                self.current_pos += self.current_vec * self.backbone_length
+                self.nodes.append(Node(nt, self.current_pos))
+                # Generate backbones
+                self.add_last_stem_backbone()
+            # Generate markers for 3' termini
+            if nucleotides and nucleotides[-1].is_three_prime:
+                self.markers.append(ArrowMarker(self.nodes[-1], self.current_vec))
+            # Layout child loop region
+            if start_idx == 0:
+                child_loop = current_stem.child_loop
+                if not child_loop.is_hinge:
+                    self.current_vec = self.current_vec.rotated(-math.pi/2)
+                self.layout_loop(child_loop)
+                if not child_loop.is_hinge:
+                    self.current_vec = self.current_vec.rotated(-math.pi/2)
+        # Generate base pairs
+        base_idx = self.nodes.index(start_node)
+        for idx in range(stem_length):
+            self.edges.append(LineEdge(self.nodes[base_idx+idx], self.nodes[-(idx+1)], EdgeType.BASE_PAIR))
+        self.current_vec = self.current_vec.normalized()
+        return None
+
+    def layout_loop(
+        self,
+        current_loop: LoopRegion,
+    ) -> None:
+        """Generate layout information for a loop region.
+
+        Parameters
+        ----------
+        current_loop : LoopRegion
+            Loop region to layout.
+        """
+        self.current_vec = self.current_vec.normalized()
+        nucleotides = current_loop.nucleotides
+        child_stems = current_loop.child_stems
+        if (current_loop.is_root
+                and child_stems
+                and child_stems[0].nucleotides[0] is nucleotides[0]):
+            self.current_vec = self.current_vec.rotated(-math.pi/2)
+            self.layout_stem(child_stems[0])
+            if not current_loop.is_hinge:
+                self.current_vec = self.current_vec.rotated(-math.pi/2)
+            nucleotides = nucleotides[1:]
+            child_stems = child_stems[1:]
+        if current_loop.is_hinge:
+            defl_angle = (
+                self.deflection_angle 
+                if nucleotides[0].is_three_prime
+                else -self.deflection_angle
+            )
+            intermediate_vec = self.current_vec.rotated(defl_angle/2)
+            delta = self.basepair_length * math.sin(defl_angle/2)
+            # Layout the second nucleotide in this loop region
+            self.current_pos += intermediate_vec * (self.backbone_length + delta)
+            self.current_vec = self.current_vec.rotated(defl_angle)
+            self.nodes.append(Node(nucleotides[1], self.current_pos))
+            self.add_last_stem_backbone()
+            # Layout child stem region
+            self.layout_stem(child_stems[0])
+            # Layout the 4th nucleotide in this loop region
+            if not current_loop.is_root:
+                self.current_pos -= intermediate_vec * (self.backbone_length - delta)
+                self.current_vec = self.current_vec.rotated(-defl_angle)
+                self.nodes.append(Node(nucleotides[3], self.current_pos))
+                self.add_last_stem_backbone()
+        else:
+            delta_angle = 2*math.pi / len(current_loop.nucleotides)
+            radius = self.basepair_length/2 / math.sin(delta_angle/2)
+            self.current_vec = self.current_vec.rotated(delta_angle)
+            stem_map = {stem.nucleotides[0]: stem for stem in child_stems}
+            # Layout nucleotides except the first and stem merge nucleotides
+            for nt in [curr for prev, curr in zip(nucleotides, nucleotides[1:]) if prev not in stem_map]:
+                self.current_pos += self.current_vec * self.basepair_length
+                self.current_vec = self.current_vec.rotated(delta_angle)
+                self.nodes.append(Node(nt, self.current_pos))
+                self.add_last_loop_backbone(radius)
+                if nt.is_three_prime:
+                    direction = self.current_vec.rotated(-delta_angle/2)
+                    self.markers.append(ArrowMarker(self.nodes[-1], direction=direction))
+                if (stem := stem_map.pop(nt, None)) is not None:
+                    self.current_vec = self.current_vec.rotated(-math.pi/2)
+                    self.layout_stem(stem)
+                    self.current_vec = self.current_vec.rotated(-math.pi/2+delta_angle)
+        self.current_vec = self.current_vec.normalized()
+        return None
+
+    def layout(self, root_loop: LoopRegion) -> None:
+        """Generate a complete layout starting from the root loop region.
+        
+        Parameters
+        ----------
+        root_loop : LoopRegion
+            Root loop region of the secondary structure tree.
+        """
+        self.current_pos = Vec2(0, 0)
+        self.current_vec = Vec2(1, 0)
+        nucleotides = root_loop.nucleotides
+        delta_angle = 2*math.pi / len(nucleotides)
+        if root_loop.child_stems:
+            # Adjust the layout so that the first stem region extends upward
+            offset = nucleotides.index(root_loop.child_stems[0].nucleotides[0])
+            for _ in range(offset):
+                self.current_vec = self.current_vec.rotated(-delta_angle)
+                self.current_pos -= self.backbone_length * self.current_vec
+            if offset != 0:
+                self.current_vec = self.current_vec.rotated(-delta_angle)
+            self.nodes.append(Node(nucleotides[0], self.current_pos))
+            self.layout_loop(root_loop)
+        else:
+            # Layout for secondary structures without base pairs
+            self.nodes.append(Node(nucleotides[0], self.current_pos))
+            for nt in nucleotides[1:]:
+                self.current_pos += self.backbone_length * self.current_vec
+                self.nodes.append(Node(nt, self.current_pos))
+                self.edges.append(LineEdge(self.nodes[-2], self.nodes[-1], EdgeType.BACKBONE))
+            self.markers.append(ArrowMarker(self.nodes[-1], self.current_vec))
+        return LayoutResult(self.nodes, self.edges, self.markers)
+
+def layout(root_loop):
+    return RadialLayoutEngine().layout(root_loop)