biolect 0.0.0.dev1__py3-none-any.whl

biolect/__init__.py

@@ -0,0 +1,27 @@
+"""Biolect
+
+This module initializes the Biolect DSL framework at its highest level.
+"""
+# ─── import statements ────────────────────────────────────────────────── ✦✦ ─
+from . import core, formats, integrations, operations, utilities, visualization
+
+from .operations import (
+    PackedSequence, SequenceBatch, SequenceStream,
+    pack_sequence, unpack_sequence, vectorized_decode
+)
+
+
+__all__ = [
+    # ─── module-level exports ────────────────────────────────────────────────
+    "core", "formats", "integrations", "operations", "utilities",
+    "visualization",
+
+    # ─── class-level exports ─────────────────────────────────────────────────
+    "PackedSequence", "SequenceBatch", "SequenceStream",
+
+    # ─── function-level exports ──────────────────────────────────────────────
+    "pack_sequence", "unpack_sequence", "vectorized_decode",
+
+    # ─── object-level exports ────────────────────────────────────────────────
+    # ...
+]

biolect/core/dtypes.py

@@ -0,0 +1,62 @@
+"""Core Data Types
+
+This module defines the framework's core data types.
+"""
+# ─── import statements ────────────────────────────────────────────────── ✦✦ ─
+
+# standard library import
+from __future__ import annotations
+from abc import ABC, abstractmethods
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import (
+    # types
+    Any, Final, Iterator, NamedTuple, Protocol, TypeAlias, TypeVar,
+
+    # descriptors
+    final, overload, runtime_checkable
+)
+
+# third-party imports
+import numpy as np
+
+from Bio import SeqIO
+from Bio.Seq import Seq
+from returns import Maybe, Result
+
+# local imports
+# ...
+
+
+# ─── enums ────────────────────────────────────────────────────────────── ✦✦ ─
+
+
+class Alphabet(Enum):
+    """An enumeration of the alphabets used in sequencing."""
+    AA  = auto()
+    DNA = auto()
+    RNA = auto()
+    
+
+
+# ─── typing ───────────────────────────────────────────────────────────── ✦✦ ─
+
+T: TypeVar = TypeVar("T")
+E: TypeVar = TypeVar("E")
+S: TypeVar = TypeVar("S")
+U: TypeVar = TypeVar("U")
+
+
+@runtime_checkable
+class Parseable(Protocol):
+    ...
+
+
+@dataclass
+class Domain(Enum):
+    ...
+
+
+class Genome(ABC):
+    domain: Domain

biolect/core/errors/__init__.py

@@ -0,0 +1,26 @@
+"""Core Error Framework
+
+This module defines the Biolect DSL's core error-handling mechanisms.
+"""
+# ─── import statements ────────────────────────────────────────────────── ✦✦ ─
+from . import handlers, monadic, recovery, types
+
+from .handlers import ErrorHandler, DefaultErrorHandler
+
+__all__ = [
+    # ─── module-level exports ────────────────────────────────────────────────
+    "handlers", "monadic", "recovery", "types"
+
+    # ─── class-level exports ─────────────────────────────────────────────────
+
+    # error handlers
+    "ErrorHandler", "DefaultErrorHandler"
+
+    # monadic error handling
+
+    # error recovery
+    "Recovery",
+
+    # error typedefs
+    "SequencingError"
+]

biolect/core/errors/etypes.py

@@ -0,0 +1,55 @@
+"""Error Types
+
+This module defines the Biolect DSL framework's error types.
+"""
+
+# standard-libary imports
+
+# third-party imports
+# ...
+
+# local imports
+# ...
+
+
+# ─── error type hierarchy ─────────────────────────────────────────────── ✦✦ ─
+class BiolectError(Exception):
+    """Base exception class for the Biolect DSL framework."""
+    pass
+
+
+class DataFormatError(BiolectError):
+    """Base class for all sequence format and structure violations."""
+    def __init__(
+        self,
+        sequence,
+        position: int | None = None,
+        expected_alphabet: Alphabet | None = None
+    ) -> None:
+        self.sequence = sequence
+        self.position = position
+        self.expected_alphabet = expected_alphabet
+        super().__init__(f"Formatting error at position {position}.")
+
+
+class InvalidSequenceError(DataFormatError):
+    """Raised when invalid characters are detected in a sequence."""
+    def __init__(
+        self,
+        sequence,
+        position: int | None = None,
+        expected_alphabet: Alphabet | None = None
+    ) -> None:
+        self.sequence = sequence
+        self.position = position
+        self.expected_alphabet = expected_alphabet
+        super().__init__(f"Invalid sequence at position {position}.")
+
+
+class FileFormatError(DataFormatError):
+    """Raised when the file format does not match the expected standard."""
+    def __init__(self, filepath, expected_format, detected_format=None):
+        self.filepath = filepath
+        self.expected_format = expected_format
+        self.detected_format = detected_format
+

biolect/core/errors/handlers.py

@@ -0,0 +1,76 @@
+"""Core Error Handlers
+
+This module implements the core error-handling logic for
+Biolect workflows.
+"""
+# ─── import statements ────────────────────────────────────────────────── ✦✦ ─
+
+# standard library imports
+from abc import ABC, abstractmethod
+
+# third-party imports
+# ...
+
+# local imports
+from .etypes import BiolectError, FileFormatError
+
+
+class ErrorHandler(ABC):
+    @abstractmethod
+    def attempt_recovery(
+        self,
+        error: BiolectError,
+        context: dict
+    ) -> bool:
+        """Attempt to recover from a raised exception."""
+        ...
+
+    @abstractmethod
+    def should_retry(
+        self,
+        error: BiolectError,
+        attempt_count: int
+    ) -> bool:
+        """Determine if the recovery operation should be reattempted."""
+        ...
+
+
+class FileFormatErrorHandler(ErrorHandler):
+    def attempt_recovery(
+        self,
+        error: FileFormatError,
+        context: dict
+    ) -> bool:
+        """Attempt to recover from an file formatting error.
+
+        Args:
+          error (FileFormatError):
+            The exception object raised by the caller.
+          context (dict):
+            A dictionary object that contains details about the context
+            surrounding the error.
+
+        Returns:
+            `True` if successful, otherwise `False`.
+        """
+        pass
+
+    
+    def should_retry(
+        self,
+        error: FileFormatError,
+        context: dict
+    ) -> bool:
+        """Deterimine if the recovery operation should be reattempted.
+
+        Args:
+          error (FileFormatError):
+            The exception object raised by the caller.
+          context (dict):
+            A dictionary object that contains details about the context
+            surrounding the error.
+
+        Returns:
+            `True` if successful, otherwise `False`.
+        """
+        pass

biolect/operations/__init__.py

@@ -0,0 +1,26 @@
+"""Operations Framework Initialization
+
+This module provides the initialization logic for the Biolect DSL's
+operations framework at a high level.
+"""
+from . import (
+    alignment, analysis, annotation, phylogenetics,
+    sequencing, utilities, visualization
+)
+
+from .sequencing import (
+    PackedSequence, SequenceStream, SequenceBatch,
+    pack_sequence, unpack_sequence, vectorized_decode
+)
+
+__all__ = [
+    # ─── module-level exports ────────────────────────────────────────────────
+    "alignment", "analysis", "annotation", "phylogenetics",
+    "sequencing", "utilities", "visualization",
+
+    # ─── class-level exports ─────────────────────────────────────────────────
+    "PackedSequence", "SequenceStream", "SequenceBatch",
+
+    # ─── function-level exports ──────────────────────────────────────────────
+    "pack_sequence", "unpack_sequence", "vectorized_decode"
+]

biolect/operations/sequencing/__init__.py

@@ -0,0 +1,28 @@
+"""Sequencing Framework Initialization
+
+This module provides the initialization logic for the Biolect DSL
+sequencing framework.
+"""
+# ─── import statements ────────────────────────────────────────────────── ✦✦ ─
+from . import analysis, encoding, manipulation, search, translation
+
+from .encoding import (
+    DECODE_TABLE, ENCODE_TABLE,
+    PackedSequence, SequenceBatch, SequenceStream,
+    iter_kmers, pack_sequence, unpack_sequence, vectorized_decode
+)
+
+
+__all__ = [
+    # ─── constants ───────────────────────────────────────────────────────────
+    "DECODE_TABLE", "ENCODE_TABLE",
+
+    # ─── modules ─────────────────────────────────────────────────────────────
+    "analysis", "encoding", "manipulation", "search", "translation",
+
+    # ─── classes ─────────────────────────────────────────────────────────────
+    "PackedSequence", "SequenceBatch", "SequenceStream",
+
+    # ─── functions ───────────────────────────────────────────────────────────
+    "iter_kmers", "pack_sequence", "unpack_sequence", "vectorized_decode"
+]

biolect/operations/sequencing/analysis.py

@@ -0,0 +1,16 @@
+"""Sequence Analysis
+
+This module defines the Biolect DSL sequence analysis engine.
+"""
+# ─── import statements ────────────────────────────────────────────────── ✦✦ ─
+
+# standard library imports
+from __future__ import annotations
+from collections.abc import Generator
+
+
+# third-party imports
+# ...
+
+# local imports
+# ...

biolect/operations/sequencing/encoding.py

@@ -0,0 +1,193 @@
+"""Core Encodings
+
+This module defines the encodings that Biolect uses in its
+approach to sequence compression.
+"""
+# ─── import statements ────────────────────────────────────────────────── ✦✦ ─
+
+# standard library imports
+from collections.abc import Generator
+from typing import Final, Iterator, NamedTuple
+
+# third-party imports
+import Bio
+import numpy as np
+
+# local imports
+
+
+# ─── interface ────────────────────────────────────────────────────────── ✦✦ ─
+
+class PackedSequence(NamedTuple):
+    data: np.ndarray
+    length: int
+    ambiguous_positions: dict[int, str] | None
+
+
+# ─── bit-packing ──────────────────────────────────────────────────────── ✦✦ ─
+
+ENCODE_TABLE = str.maketrans("ATGC", "\x00\x01\x02\x03")
+DECODE_TABLE = ["A", "T", "G", "C"]
+
+def pack_sequence(seq: str | Bio.Seq) -> (
+    tuple[np.ndarray, dict[int, str] | None]
+):
+    """Pack a sequence of DNA nucleobases with ambiguity extraction."""
+    cleaned = []
+    ambiguous = {}
+
+    for i, base in enumerate(seq.upper()):
+        if base in "ATGC":
+            cleaned.append(ord(base.translate(ENCODE_TABLE)))
+        else:
+            # Use "A" as a plaecholder, and track the base.
+            cleaned.append(0)
+            ambiguous[i] = base
+
+    # ─── pack 4 bases per byte ───────────────────────────────────────────────
+    packed_length = (len(cleaned) + 3) // 4
+    packed = np.zeros(packed_length, dtype=np.uint8)
+
+    for i, base_code in enumerate(cleaned):
+        byte_idx = i // 4
+        bit_offset = (i % 4) * 2
+        packed[byte_idx] |= base_code << bit_offset
+
+    return packed, ambiguous if ambiguous else None
+
+
+def unpack_sequence(packed_seq: PackedSequence, start: int, end: int) -> str:
+    """Unpack a bit-packed subsequence into string representation."""
+    result = []
+
+    for pos in range(start, min(end, packed_seq.length)):
+        # Check for ambiguous base.
+        if packed_seq.ambiguous_positions and (
+            pos in packed_seq.ambiguous_positions
+        ):
+            result.append(packed_seq.ambiguous_positions[pos])
+            continue
+
+        # Extract from packed data
+        byte_idx = pos // 4
+        bit_offset = (pos % 4) * 2
+        base_code = (packed_seq.data[byte_idx] >> bit_offset) & 0b11
+        result.append(DECODE_TABLE[base_code])
+
+    return "".join(result)
+
+
+def vectorized_decode(packed_seq: PackedSequence) -> str:
+    """High-performance full-sequence decode using NumPy."""
+    if packed_seq.length == 0:
+        return ""
+
+    # Expand packed bytes to individual bases.
+    expanded = np.zeros(packed_seq.length, dtype=np.uint8)
+
+    for i in range(packed_seq.length):
+        byte_idx = i // 4
+        bit_offset = (i % 4) * 2
+        expanded[i] = (packed_seq.data[byte_idx] >> bit_offset) & 0b11
+
+    base_chars = np.array(DECODE_TABLE, dtype="U1")[expanded]
+    result = "".join(base_chars)
+
+    # Apply ambiguous base substitutions.
+    if packed_seq.ambiguous_positions:
+        result_list = list(result)
+        for pos, ambiguous_base in packed_seq.ambiguous_positions.items():
+            if pos < len(result_list):
+                result_list[pos] = ambiguous_base
+        result = "".join(result_list)
+
+    return result
+
+
+def iter_kmers(packed_seq: PackedSequence, k: int) -> (
+    Generator[str, None, None]
+):
+    """Memory-efficient k-mer generation."""
+    if packed_seq.length < k:
+        return
+
+    # Use a "sliding window" approach.
+    window = unpack_sequence(packed_seq, 0, k)
+    yield window
+
+    for i in range(1, packed_seq.length - k + 1):
+        # "Slide" the window by one position.
+        new_pos = i + k - 1
+        
+        if packed_seq.ambiguous_positions and (
+            new_pos in packed_seq.ambiguous_positions
+        ):
+            new_base = packed_seq.ambiguous_positions[new_pos]
+        else:
+            byte_idx = new_pos // 4
+            bit_offset = (new_pos % 4) * 2
+            base_code = (packed_seq.data[byte_idx] >> bit_offset) & 0b11
+            new_base = DECODE_TABLE[base_code]
+
+        window = window[1:] + new_base
+        yield window
+
+class SequenceStream:
+    def __init__(self, file_handle):
+        self.file_handle = file_handle
+        self._buffer = bytearray(8192)
+        
+    
+    def iter_sequences(self) -> Generator[PackedSequence, None, None]:
+        """Yield packed sequences from a FASTA stream."""
+        current_header = None
+        sequence_parts = []
+
+        for line in self.file_handle:
+            line = line.strip()
+            if line.startswith(">"):
+                if current_header and sequence_parts:
+                    # Process accumulated sequence
+                    full_seq = "".join(sequence_parts)
+                    packed_data, ambiguous = pack_sequence(full_seq)
+
+                    yield PackedSequence(
+                        data=packed_data,
+                        length=len(full_seq),
+                        ambiguous_positions=ambiguous
+                    )
+
+                current_header = line[1:]
+                sequence_parts = []
+            else:
+                sequence_parts.append(line)
+            
+        # Handle final sequence
+        if current_header and sequence_parts:
+            full_seq = "".join(sequence_parts)
+            packed_data, ambiguous = pack_sequence(full_seq)
+            
+            yield PackedSequence(
+                data=packed_data,
+                length=len(full_seq),
+                ambiguous_positions=ambiguous
+            )
+
+
+class SequenceBatch:
+    """Process multiple sequences efficiently."""
+
+    def __init__(self, batch_size: int = 1000) -> None:
+        self.batch_size = batch_size
+        self._sequence_buffer = []
+
+
+    def process_batch(self, sequences: list[PackedSequence]) -> Iterator[str]:
+        """Vectorized processing of a sequence batch."""
+        # Sort by length for better cache behavior.
+        sorted_seqs = sorted(sequences, key=lambda s: s.length)
+
+        for seq in sorted_seqs:
+            yield vectorized_decode(seq)
+
+