pymethyl2sam 0.1.2__py3-none-any.whl

pymethyl2sam/__init__.py

@@ -0,0 +1,17 @@
+"""
+PyMethyl2Sam - A Python library for methylation data processing and BAM file generation.
+
+Copyright (c) 2025
+"""
+
+from importlib.metadata import version
+
+__version__ = version("pymethyl2sam")
+
+# Import core components
+from .core.genomics import *
+from .core.sequencing import *
+from .core.errors import *
+from .simulator import MethylationSimulator
+
+__all__ = ["MethylationSimulator"]

pymethyl2sam/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core domain logic for methylation modeling, sequencing, and errors."""
+
+from .errors import ErrorModel
+from .genomics import MethylationSite
+
+__all__ = ["MethylationSite", "ErrorModel"]

pymethyl2sam/core/errors.py

@@ -0,0 +1,201 @@
+"""Error model for simulating sequencing errors and mutations."""
+
+import random
+from dataclasses import dataclass
+from typing import Dict, List, Tuple
+
+
+@dataclass
+class ErrorParameters:
+    """Parameters for error simulation."""
+
+    mismatch_rate: float
+    insertion_rate: float
+    deletion_rate: float
+
+    def __post_init__(self):
+        """Validate error parameters."""
+        if not 0 <= self.mismatch_rate <= 1:
+            raise ValueError("Mismatch rate must be between 0 and 1")
+        if not 0 <= self.insertion_rate <= 1:
+            raise ValueError("Insertion rate must be between 0 and 1")
+        if not 0 <= self.deletion_rate <= 1:
+            raise ValueError("Deletion rate must be between 0 and 1")
+
+
+class ErrorModel:
+    """Handles sequencing error simulation and mutations."""
+
+    def __init__(self, parameters: ErrorParameters):
+        """Initialize error model.
+
+        Args:
+            parameters: Error simulation parameters
+        """
+        self.parameters = parameters
+        self._mismatch_bases = {
+            "A": ["C", "G", "T"],
+            "C": ["A", "G", "T"],
+            "G": ["A", "C", "T"],
+            "T": ["A", "C", "G"],
+            "N": ["A", "C", "G", "T"],  # Handle 'N' bases
+        }
+
+    def introduce_errors(self, sequence: str) -> Tuple[str, List[Dict]]:
+        """Introduce sequencing errors into a sequence.
+
+        Args:
+            sequence: Original DNA sequence
+
+        Returns:
+            Tuple of (modified_sequence, error_log)
+        """
+        modified_sequence = list(sequence)
+        error_log = []
+        i = 0
+        total_error_rate = (
+            self.parameters.mismatch_rate
+            + self.parameters.insertion_rate
+            + self.parameters.deletion_rate
+        )
+
+        while i < len(modified_sequence):
+            # First, determine if any error should occur at this position
+            if random.random() < total_error_rate:
+                error_type = self._choose_error_type()
+                base = modified_sequence[i]
+
+                if error_type == "mismatch":
+                    new_base = random.choice(
+                        self._mismatch_bases.get(base, ["A", "C", "G", "T"])
+                    )
+                    modified_sequence[i] = new_base
+                    error_log.append(
+                        {
+                            "position": i,
+                            "type": "mismatch",
+                            "original": base,
+                            "new": new_base,
+                        }
+                    )
+                elif error_type == "insertion":
+                    inserted_base = random.choice(["A", "C", "G", "T"])
+                    modified_sequence.insert(i, inserted_base)
+                    error_log.append(
+                        {"position": i, "type": "insertion", "inserted": inserted_base}
+                    )
+                    i += 1  # Skip the newly inserted base to avoid cascading errors
+                elif error_type == "deletion":
+                    deleted_base = modified_sequence.pop(i)
+                    error_log.append(
+                        {"position": i, "type": "deletion", "deleted": deleted_base}
+                    )
+                    continue  # Loop again at the same index `i` on the now-shorter list
+            i += 1
+        return "".join(modified_sequence), error_log
+
+    def _choose_error_type(self) -> str:
+        """Choose an error type based on the relative rates of configured errors.
+
+        Returns:
+            Error type ("mismatch", "insertion", or "deletion")
+        """
+        total_rate = (
+            self.parameters.mismatch_rate
+            + self.parameters.insertion_rate
+            + self.parameters.deletion_rate
+        )
+        if total_rate == 0:
+            return "none"  # No errors to choose from
+
+        # Normalize rates to create a probability distribution
+        norm_mismatch = self.parameters.mismatch_rate / total_rate
+        norm_insertion = self.parameters.insertion_rate / total_rate
+        rand = random.random()
+
+        if rand < norm_mismatch:
+            return "mismatch"
+        if rand < norm_mismatch + norm_insertion:
+            return "insertion"
+        return "deletion"
+
+    @staticmethod
+    def calculate_quality_scores(
+        sequence_length: int, base_quality: int = 30
+    ) -> List[int]:
+        """Calculate quality scores for a sequence.
+
+        Args:
+            sequence_length: Length of the sequence
+            base_quality: Base quality score (Phred scale)
+
+        Returns:
+            List of quality scores
+        """
+        if sequence_length < 0:
+            raise ValueError("Sequence length cannot be negative.")
+        return [base_quality] * sequence_length
+
+    def introduce_methylation_errors(
+        self, methylation_sites: List[Dict], error_rate: float = 0.01
+    ) -> List[Dict]:
+        """Introduce errors in methylation detection.
+
+        Args:
+            methylation_sites: List of methylation site dictionaries
+            error_rate: Rate of methylation detection errors
+
+        Returns:
+            Modified list of methylation sites without altering the original.
+        """
+        if not 0 <= error_rate <= 1:
+            raise ValueError("Methylation error rate must be between 0 and 1")
+
+        modified_sites = []
+        for site in methylation_sites:
+            site_copy = site.copy()  # Avoid modifying the original list of dicts
+            if random.random() < error_rate:
+                # Flip methylation state
+                site_copy["detected"] = not site_copy.get("detected", True)
+                site_copy["error"] = True
+            else:
+                site_copy["error"] = False
+            modified_sites.append(site_copy)
+        return modified_sites
+
+    def simulate_sequencing_artifacts(
+        self, sequence: str, position: int
+    ) -> Tuple[str, Dict]:
+        """Simulate sequencing artifacts at a specific position.
+
+        Args:
+            sequence: DNA sequence
+            position: Position to introduce artifact
+
+        Returns:
+            Tuple of (modified_sequence, artifact_info)
+        """
+        if not 0 <= position < len(sequence):
+            raise ValueError("Position must be a valid index in the sequence.")
+
+        artifact_types = ["stutter", "dropout", "amplification_bias"]
+        artifact_type = random.choice(artifact_types)
+        modified_sequence = list(sequence)
+        artifact_info = {"type": artifact_type, "position": position}
+
+        if artifact_type == "stutter":
+            base = modified_sequence[position]
+            modified_sequence.insert(position, base)
+            artifact_info["repeated_base"] = base
+        elif artifact_type == "dropout":
+            deleted_base = modified_sequence.pop(position)
+            artifact_info["deleted_base"] = deleted_base
+        elif artifact_type == "amplification_bias":
+            base_to_change = modified_sequence[position]
+            bias_bases = ["A", "T"]  # Example bias
+            if base_to_change not in bias_bases:
+                new_base = random.choice(bias_bases)
+                modified_sequence[position] = new_base
+                artifact_info["original_base"] = base_to_change
+                artifact_info["biased_base"] = new_base
+        return "".join(modified_sequence), artifact_info

pymethyl2sam/core/genomics.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from enum import Enum
+
+
+# Methylation modifications
+class ModificationType(Enum):
+    C5MC = "5mC"
+    C5HMC = "5hmC"
+    C5FC = "5fC"
+    C5CAC = "5caC"
+
+
+class StrandOrientation(Enum):
+    FORWARD = "+"
+    BACKWARD = "-"
+    RANDOM = "?"
+
+    def to_is_reverse(self) -> bool:
+        if self is StrandOrientation.FORWARD:
+            return False
+        if self is StrandOrientation.BACKWARD:
+            return True
+        if self is StrandOrientation.RANDOM:
+            return random.choice([True, False])
+        raise ValueError(f"Unsupported strand orientation: {self}")
+
+    def __repr__(self):
+        return self.value
+
+
+@dataclass(frozen=True)
+class Chromosome:
+    """
+    Represents a simulated chromosome with defined CpG sites and simulation regions.
+    """
+
+    name: str
+    length: int
+
+
+@dataclass(frozen=True, order=True)
+class MethylationSite:
+    """
+    Represents a CpG site in a genome with a probability of being methylated.
+    """
+
+    position: int  # Zero-based position in reference
+    context: str = "CG"  # Methylation context (e.g., "CG", "CHG")
+    modification: ModificationType = ModificationType("5mC")
+    methylation_prob: float = 0.5
+
+    def __post_init__(self):
+        """Validate methylation site parameters."""
+        if not 0.0 <= self.methylation_prob <= 1.0:
+            raise ValueError(
+                f"methylation_prob must be in [0, 1], got {self.methylation_prob}"
+            )
+        if self.position < 0:
+            raise ValueError("Position must be non-negative")
+        if not self.context:
+            raise ValueError("Context cannot be empty")
+
+    def with_position(self, new_position: int) -> MethylationSite:
+        return MethylationSite(
+            methylation_prob=self.methylation_prob,
+            position=new_position,
+            context=self.context,
+            modification=self.modification,
+        )
+
+    def get_cytosine_position(self, is_reverse_strand: bool):
+        return self.position + 1 if is_reverse_strand else self.position
+
+
+@dataclass(frozen=True)
+class GenomicInterval:
+    """
+    Represents a genomic interval using half-open coordinates [start, end).
+
+    Attributes:
+        start (int): Start coordinate (inclusive).
+        end (int): End coordinate (exclusive).
+    """
+
+    start: int  # inclusive
+    end: int  # exclusive (half-open)
+    is_reverse: bool
+
+    def __post_init__(self):
+        """Validate region parameters after initialization."""
+        if self.start < 0:
+            raise ValueError("Start position must be non-negative")
+        if self.end < self.start:
+            raise ValueError("End position must not be smaller than start position")
+
+    @property
+    def length(self) -> int:
+        """Return the length of the region (0-based, half-open)."""
+        return self.end - self.start
+
+    def contains(self, position: int) -> bool:
+        """
+        Check if a specific position is within the region.
+
+        Args:
+            position (int): Genomic position to check.
+
+        Returns:
+            bool: True if the position is within the region.
+        """
+        # pylint: disable=W0511
+        # TODO: validate consistency on BW strand
+        return self.start <= position < self.end

pymethyl2sam/core/reference_genome.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import logging
+import os
+from abc import ABC, abstractmethod
+from functools import lru_cache
+from urllib.request import urlretrieve
+from urllib.error import URLError, HTTPError
+from typing import Optional
+
+from pysam.libcfaidx import FastxFile
+from pysam import SamtoolsError  # more specific error
+
+from pymethyl2sam.core.genomics import GenomicInterval
+
+
+# pylint: disable=R0903
+class ReferenceGenomeProvider(ABC):
+    @abstractmethod
+    def get_sequence(self, chromosome: str, region: GenomicInterval) -> str:
+        """Get the reference sequence for a specific region."""
+
+
+# pylint: disable=R0903
+class ConstantReferenceGenome(ReferenceGenomeProvider):
+    def get_sequence(self, chromosome: str, region: GenomicInterval) -> str:
+        return "A" * region.length
+
+
+# pylint: disable=R0903
+class Hg38ReferenceGenome(ReferenceGenomeProvider):
+    def __init__(
+        self,
+        base_url: str = "http://hgdownload.soe.ucsc.edu/goldenPath/hg38/chromosomes/",
+        cache_dir: str = "hg38_cache",
+    ):
+        self.base_url = base_url
+        self.cache_dir = cache_dir
+        os.makedirs(self.cache_dir, exist_ok=True)
+
+    def get_sequence(self, chromosome: str, region: GenomicInterval) -> str:
+        """Public method to get a sequence slice with boundary checks."""
+        chromosome_sequence = self._get_full_chromosome_sequence(chromosome)
+        if chromosome_sequence is None:
+            raise FileNotFoundError(
+                f"Could not retrieve sequence for chromosome '{chromosome}'. "
+                f"Expected file: {chromosome}.fa.gz in {self.cache_dir}"
+            )
+
+        chromosome_length = len(chromosome_sequence)
+        if region.end > chromosome_length:
+            raise ValueError(
+                f"Requested interval {region.start}-{region.end} is outside the "
+                f"bounds of chromosome '{chromosome}' (length: {chromosome_length})."
+            )
+
+        return chromosome_sequence[region.start : region.end]
+
+    @lru_cache(maxsize=32)
+    def _get_full_chromosome_sequence(self, chromosome: str) -> Optional[str]:
+        """
+        Downloads, reads, and caches the entire sequence for a given chromosome.
+        """
+        fasta_filename = f"{chromosome}.fa.gz"
+        fasta_path = os.path.join(self.cache_dir, fasta_filename)
+
+        if not os.path.exists(fasta_path):
+            try:
+                logging.info(
+                    f"Downloading {fasta_filename} to cache directory '{self.cache_dir}'..."
+                )
+                urlretrieve(self.base_url + fasta_filename, fasta_path)
+            except (URLError, HTTPError) as e:
+                raise FileNotFoundError(
+                    f"Failed to download {fasta_filename}: {e.reason}"
+                ) from e
+
+        try:
+            with FastxFile(fasta_path) as ref:
+                for entry in ref:
+                    if entry.name == chromosome:
+                        logging.info(f"Caching full sequence for {entry.name}")
+                        return entry.sequence
+        except (OSError, SamtoolsError) as e:
+            logging.error(f"Error reading FASTA file '{fasta_path}': {e}")
+
+        return None

pymethyl2sam/core/sequencing.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from random import randint
+from typing import Iterable
+
+from pymethyl2sam.core.genomics import (
+    MethylationSite,
+    StrandOrientation,
+    GenomicInterval,
+)
+
+
+@dataclass(frozen=True)
+class ReadQuality:
+    """Quality scores for sequencing and mapping."""
+
+    sequencing_score: int = 32
+    mapping_score: int = 100
+
+    def __post_init__(self):
+        if not 0 <= self.sequencing_score <= 50:
+            raise ValueError("sequencing_score must be in the range [0, 50].")
+        if not 0 <= self.mapping_score <= 255:
+            raise ValueError("mapping_score must be in the range [0, 255].")
+
+
+@dataclass(frozen=True, order=True)
+class ReadTemplate(GenomicInterval):
+    """Template for generating a single read with quality and methylation sites."""
+
+    quality: ReadQuality
+    local_methylated_sites: list[MethylationSite]
+
+
+@dataclass(frozen=True)
+class ReadGenerationStrategy(ABC):
+    """Abstract base class for read generation strategies."""
+
+    @abstractmethod
+    def generate_read_intervals(
+        self, region: GenomicInterval, read_length: int
+    ) -> Iterable[GenomicInterval]:
+        pass
+
+    @property
+    @abstractmethod
+    def total_reads(self) -> int:
+        pass
+
+
+@dataclass(frozen=True)
+class PatternedReadData:
+    """Data class representing a single read pattern with offset and orientation."""
+
+    offset: int
+    orientation: StrandOrientation
+
+
+@dataclass(frozen=True)
+class PatternStrategy(ReadGenerationStrategy):
+    data: Iterable[PatternedReadData]
+
+    def generate_read_intervals(
+        self, region: GenomicInterval, read_length: int
+    ) -> Iterable[GenomicInterval]:
+        for read in self.data:
+            start = region.start + read.offset
+            yield GenomicInterval(
+                start=start,
+                end=start + read_length,
+                is_reverse=read.orientation.to_is_reverse(),
+            )
+
+    @property
+    def total_reads(self) -> int:
+        return len(list(self.data))
+
+    @staticmethod
+    def from_offset_orientation_pairs(
+        offsets: Iterable[int], orientations: Iterable[StrandOrientation | str]
+    ) -> PatternStrategy:
+        """Create a PatternStrategy from paired offsets and orientations.
+
+        Args:
+            offsets: Iterable of offset positions
+            orientations: Iterable of strand orientations (can be strings or StrandOrientation)
+
+        Returns:
+            PatternStrategy configured with the provided data
+        """
+        data = [
+            PatternedReadData(
+                offset=offset,
+                orientation=(
+                    orientation
+                    if isinstance(orientation, StrandOrientation)
+                    else StrandOrientation(orientation)
+                ),
+            )
+            for offset, orientation in zip(offsets, orientations)
+        ]
+        return PatternStrategy(data)
+
+    @staticmethod
+    def from_offsets(
+        offsets: Iterable[int], orientation: StrandOrientation
+    ) -> PatternStrategy:
+        """Create a PatternStrategy from offsets with a single orientation.
+
+        Args:
+            offsets: Iterable of offset positions
+            orientation: Single strand orientation for all reads
+
+        Returns:
+            PatternStrategy configured with the provided data
+        """
+        data = [
+            PatternedReadData(
+                offset=offset,
+                orientation=orientation,
+            )
+            for offset in offsets
+        ]
+        return PatternStrategy(data)
+
+
+@dataclass(frozen=True)
+class RandomStrategy(ReadGenerationStrategy):
+    """Strategy for generating reads at random positions."""
+
+    reads_per_region: int = 200
+    orientation: StrandOrientation = StrandOrientation.RANDOM
+
+    def __post_init__(self):
+        if self.reads_per_region <= 0:
+            raise ValueError("reads_per_region must be a positive integer.")
+
+    def generate_read_intervals(
+        self, region: GenomicInterval, read_length: int
+    ) -> Iterable[GenomicInterval]:
+        min_start = max(region.start - read_length + 1, 0)
+        max_start = region.end + read_length - 1
+        for _ in range(self.reads_per_region):
+            start = randint(min_start, max_start)
+            yield GenomicInterval(
+                start=start,
+                end=start + read_length,
+                is_reverse=self.orientation.to_is_reverse(),
+            )
+
+    @property
+    def total_reads(self) -> int:
+        return self.reads_per_region
+
+
+@dataclass(frozen=True)
+class EmptyStrategy(ReadGenerationStrategy):
+    """Strategy that generates no reads."""
+
+    def generate_read_intervals(
+        self, region: GenomicInterval, read_length: int
+    ) -> Iterable[GenomicInterval]:
+        return []
+
+    @property
+    def total_reads(self) -> int:
+        return 0
+
+
+@dataclass(frozen=True)
+class ReadGenerator:
+    """Generates reads using a specified strategy."""
+
+    strategy: ReadGenerationStrategy
+    read_length: int = 150
+    quality: ReadQuality = ReadQuality()
+
+    def __post_init__(self):
+        if self.read_length <= 0:
+            raise ValueError("read_length must be a positive integer.")
+
+    def generate_reads(
+        self,
+        region: GenomicInterval,
+        cpg_sites: Iterable[MethylationSite],
+    ) -> Iterable[ReadTemplate]:
+        for interval in self.strategy.generate_read_intervals(region, self.read_length):
+            local_methylated_sites = [
+                site.with_position(site.position - interval.start)
+                for site in cpg_sites
+                if interval.contains(site.position)
+            ]
+            yield ReadTemplate(
+                quality=self.quality,
+                local_methylated_sites=local_methylated_sites,
+                **interval.__dict__,
+            )
+
+    def __repr__(self):
+        """Return a string representation of the ReadGenerator."""
+
+        def format_value(val) -> str:
+            """Format a value for display in the representation."""
+            if isinstance(val, list) and len(val) == 1:
+                val = val[0]
+            if (
+                isinstance(val, str)
+                and val.isascii()
+                and 0 < len(val) <= 3
+                and val.isprintable()
+            ):
+                return val
+            return repr(val)
+
+        parts = [
+            f"{key.replace('_', ' ')}:{format_value(value)}"
+            for key, value in self.__dict__.items()
+        ]
+        return f"{self.__class__.__name__}({', '.join(parts)})"

pymethyl2sam/io/__init__.py

@@ -0,0 +1,5 @@
+"""Optional parsers and I/O for FASTA, BED, YAML, JSON."""
+
+from .genome_loader import GenomeLoader
+
+__all__ = ["GenomeLoader"]