pymethyl2sam 0.1.2__py3-none-any.whl

pymethyl2sam/io/genome_loader.py

@@ -0,0 +1,166 @@
+"""Genome loader for FASTA files."""
+
+import os
+from typing import Any, Dict, Optional, List
+
+from ..utils.logging import setup_logging
+
+logger = setup_logging(__name__)
+
+
+class GenomeLoader:
+    """Handles loading genome sequences from FASTA files."""
+
+    def __init__(self):
+        """Initialize genome loader."""
+
+    def load_genome(
+        self, genome_file: str, chromosome: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Load genome sequences from FASTA file.
+
+        Args:
+            genome_file: Path to FASTA file
+            chromosome: Specific chromosome to load (optional)
+
+        Returns:
+            Dictionary with genome data
+        """
+        if not os.path.exists(genome_file):
+            raise FileNotFoundError(f"Genome file not found: {genome_file}")
+
+        logger.info(f"Loading genome from: {genome_file}")
+
+        sequences = {}
+        current_chr = None
+        current_seq = []
+
+        with open(genome_file, "r", encoding="utf-8") as file_handle:
+            for line in file_handle:
+                line = line.strip()
+
+                if line.startswith(">"):
+                    # Save previous sequence
+                    if current_chr and current_seq:
+                        sequences[current_chr] = "".join(current_seq)
+
+                    # Parse header
+                    header = line[1:]  # Remove '>'
+                    current_chr = self._parse_chromosome_name(header)
+                    current_seq = []
+
+                    # Skip if specific chromosome requested and this isn't it
+                    if chromosome and current_chr != chromosome:
+                        current_chr = None
+                        current_seq = []
+
+                elif current_chr and line:
+                    current_seq.append(line.upper())
+
+        # Save last sequence
+        if current_chr and current_seq:
+            sequences[current_chr] = "".join(current_seq)
+
+        if chromosome and chromosome not in sequences:
+            raise ValueError(f"Chromosome {chromosome} not found in genome file")
+
+        if not sequences:
+            raise ValueError(f"No sequences found in genome file: {genome_file}")
+
+        genome_data = {
+            "file": genome_file,
+            "sequences": sequences,
+            "total_length": sum(len(seq) for seq in sequences.values()),
+        }
+
+        logger.info(
+            f"Loaded {len(sequences)} sequences with total length {genome_data['total_length']}"
+        )
+        return genome_data
+
+    def _parse_chromosome_name(self, header: str) -> str:
+        """Parse chromosome name from FASTA header.
+
+        Args:
+            header: FASTA header line
+
+        Returns:
+            Chromosome name
+        """
+        # Simple parsing - take first word after '>'
+        # This can be enhanced for different header formats
+        parts = header.split()
+        if parts:
+            return parts[0]
+        return "unknown"
+
+    def get_chromosome_list(self, genome_file: str) -> List[str]:
+        """Get list of chromosomes in genome file.
+
+        Args:
+            genome_file: Path to FASTA file
+
+        Returns:
+            List of chromosome names
+        """
+        chromosomes = []
+
+        with open(genome_file, "r", encoding="utf-8") as file_handle:
+            for line in file_handle:
+                if line.startswith(">"):
+                    header = line[1:].strip()
+                    chr_name = self._parse_chromosome_name(header)
+                    chromosomes.append(chr_name)
+
+        return chromosomes
+
+    def get_sequence_length(self, genome_file: str, chromosome: str) -> int:
+        """Get length of a specific chromosome.
+
+        Args:
+            genome_file: Path to FASTA file
+            chromosome: Chromosome name
+
+        Returns:
+            Sequence length
+        """
+        genome_data = self.load_genome(genome_file, chromosome)
+        if chromosome in genome_data["sequences"]:
+            return len(genome_data["sequences"][chromosome])
+        return 0
+
+    def validate_genome_file(self, genome_file: str) -> Dict[str, Any]:
+        """Validate genome file and return statistics.
+
+        Args:
+            genome_file: Path to FASTA file
+
+        Returns:
+            Dictionary with validation results
+        """
+        validation_results = {
+            "file_exists": False,
+            "total_sequences": 0,
+            "total_length": 0,
+            "chromosomes": [],
+            "errors": [],
+        }
+
+        try:
+            if not os.path.exists(genome_file):
+                validation_results["errors"].append(f"File not found: {genome_file}")
+                return validation_results
+
+            validation_results["file_exists"] = True
+
+            genome_data = self.load_genome(genome_file)
+            validation_results["total_sequences"] = len(genome_data["sequences"])
+            validation_results["total_length"] = genome_data["total_length"]
+            validation_results["chromosomes"] = list(genome_data["sequences"].keys())
+
+        except RuntimeError as ex:
+            validation_results["errors"].append(
+                f"Error validating genome file: {str(ex)}"
+            )
+
+        return validation_results

pymethyl2sam/simulator/__init__.py

@@ -0,0 +1,15 @@
+"""Orchestration of read and methylation simulation."""
+
+from ..core.reference_genome import ConstantReferenceGenome
+from .simulator import (
+    MethylationSimulator,
+    SequencedChromosome,
+    SequencedRegion,
+)
+
+__all__ = [
+    "MethylationSimulator",
+    "SequencedChromosome",
+    "SequencedRegion",
+    "ConstantReferenceGenome",
+]

pymethyl2sam/simulator/simulator.py

@@ -0,0 +1,208 @@
+"""Simulator class for generating aligned reads from simulated CpG methylation data."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from importlib.metadata import version, PackageNotFoundError
+from random import seed as random_seed, random
+from typing import Generator, List, Optional, Set
+
+import pysam
+from pysam.libcalignedsegment import AlignedSegment
+from pysam.libcalignmentfile import AlignmentFile, AlignmentHeader
+
+from pymethyl2sam.core.genomics import GenomicInterval, Chromosome, MethylationSite
+from pymethyl2sam.core.reference_genome import ReferenceGenomeProvider
+from pymethyl2sam.core.sequencing import ReadTemplate, ReadGenerator, ReadQuality
+from pymethyl2sam.utils.pysam import make_sam_dict, generate_mm_tag
+
+logger = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+
+@dataclass(frozen=True, init=False)
+class SequencedRegion:
+    """Represents a genomic region with associated read generation strategy."""
+
+    interval: GenomicInterval
+    read_generator: ReadGenerator
+
+    def __init__(self, start: int, end: int, read_generator: ReadGenerator):
+        object.__setattr__(self, "interval", GenomicInterval(start, end, False))
+        object.__setattr__(self, "read_generator", read_generator)
+
+
+@dataclass(frozen=True)
+class SequencedChromosome(Chromosome):
+    regions: List[SequencedRegion]
+    cpg_sites: List[MethylationSite] = field(default_factory=list)
+
+    def __post_init__(self):
+        """Validate that methylation sites do not overlap."""
+        sorted_sites = sorted(self.cpg_sites, key=lambda s: s.position)
+        for prev, curr in zip(sorted_sites, sorted_sites[1:]):
+            prev_end = prev.position + len(prev.context)
+            curr_start = curr.position
+            if curr_start < prev_end:
+                raise ValueError(
+                    f"Overlapping methylation sites detected:\n"
+                    f"  Site 1: pos={prev.position}, context='{prev.context}'\n"
+                    f"  Site 2: pos={curr.position}, context='{curr.context}'"
+                )
+
+    def generate_reads(self) -> Generator[ReadTemplate, None, None]:
+        """Yield reads for each defined region in the chromosome."""
+        for region in self.regions:
+            logger.debug(f"Generating reads for region: {region}")
+            yield from region.read_generator.generate_reads(
+                region.interval, self.cpg_sites
+            )
+
+
+@dataclass(frozen=True)
+class SimulatedRead(GenomicInterval):
+    """Represents a simulated read with sequence, methylation sites, and quality."""
+
+    chrom: str
+    sequence: str
+    methylated_sites: Set[MethylationSite]
+    quality: ReadQuality
+
+    @staticmethod
+    def from_template(
+        template: ReadTemplate, chrom: str, reference_genome: ReferenceGenomeProvider
+    ) -> SimulatedRead:
+        """Construct a simulated read from a template and reference sequence."""
+        sequence = bytearray(
+            reference_genome.get_sequence(chrom, template).upper(), "ascii"
+        )
+        sampled_sites: Set[MethylationSite] = set()
+
+        for site in template.local_methylated_sites:
+            SimulatedRead._apply_site(sequence, site)
+            if site.methylation_prob >= 1.0 or random() < site.methylation_prob:
+                sampled_sites.add(site)
+
+        return SimulatedRead(
+            chrom=chrom,
+            start=template.start,
+            end=template.end,
+            is_reverse=template.is_reverse,
+            sequence=sequence.decode("ascii"),
+            quality=template.quality,
+            methylated_sites=sampled_sites,
+        )
+
+    @staticmethod
+    def _apply_site(sequence: bytearray, site: MethylationSite) -> None:
+        """Apply a methylation site's context to the sequence in-place."""
+        start = max(0, site.position)
+        end = min(start + len(site.context), len(sequence))
+        sequence[start:end] = site.context[: end - start].encode("ascii")
+
+    def to_aligned_segment(self, header: AlignmentHeader) -> AlignedSegment:
+        """Convert this simulated read into a pysam AlignedSegment."""
+        segment = AlignedSegment.from_dict(
+            make_sam_dict(
+                chrome=self.chrom,
+                start=self.start,
+                sequence=self.sequence,
+                quality=self.quality,
+                is_reverse=self.is_reverse,
+            ),
+            header=header,
+        )
+        segment.set_tag("MD", str(self.length), value_type="Z")
+        segment.set_tag("NM", 0, value_type="i")
+
+        if self.methylated_sites and self.sequence:
+            mm_tag = generate_mm_tag(
+                self.sequence,
+                self.methylated_sites,
+                self.is_reverse,
+            )
+            segment.set_tag("MM", mm_tag, value_type="Z")
+
+        return segment
+
+
+@dataclass
+class MethylationSimulator:
+    """Main simulator class for generating methylation-aware reads."""
+
+    chromosomes: List[SequencedChromosome]
+    reference_genome: ReferenceGenomeProvider
+
+    def simulate_reads(
+        self,
+        output_file: str,
+        seed: Optional[int] = None,
+        is_sorted: bool = True,
+    ) -> None:
+        """Simulate reads and write to a BAM file.
+
+        Args:
+            output_file: Path to output BAM file
+            seed: Random seed for reproducibility
+            is_sorted: Whether to sort the BAM file after writing
+        """
+        if seed is not None:
+            random_seed(seed)
+
+        header = self.create_header()
+        with AlignmentFile(output_file, "wb", header=header) as out_bam:
+            logger.info("Beginning read simulation...")
+            for chrom in self.chromosomes:
+                logger.debug(f"Simulating reads for chromosome: {chrom.name}")
+                for template in chrom.generate_reads():
+                    read = SimulatedRead.from_template(
+                        template=template,
+                        chrom=chrom.name,
+                        reference_genome=self.reference_genome,
+                    )
+                    out_bam.write(read.to_aligned_segment(header))
+            logger.info("Read simulation complete.")
+
+        if is_sorted:
+            logger.info(f"Sorting output file: {output_file}")
+            pysam.sort(
+                "-o", output_file, output_file, "--write-index", catch_stdout=False
+            )
+
+    def create_header(self) -> AlignmentHeader:
+        """Create a SAM/BAM header based on the simulated chromosomes."""
+        try:
+            tool_version = version("pymethyl2sam")
+        except PackageNotFoundError:
+            tool_version = "unknown"
+
+        header_dict = {
+            "HD": {"VN": "1.6", "SO": "coordinate"},
+            "SQ": [
+                {"SN": chrom.name, "LN": chrom.length} for chrom in self.chromosomes
+            ],
+            "RG": [],
+            "PG": [
+                {
+                    "ID": "pymethyl2sam",
+                    "VN": tool_version,
+                    "CL": "pymethyl2sam",
+                }
+            ],
+        }
+        return AlignmentHeader.from_dict(header_dict)
+
+    @property
+    def total_reads(self) -> int:
+        """Total number of reads across all chromosomes and regions."""
+        return sum(
+            region.read_generator.strategy.total_reads
+            for chrom in self.chromosomes
+            for region in chrom.regions
+        )
+
+    @property
+    def total_methylation_sites(self) -> int:
+        """Total number of methylation sites across all chromosomes."""
+        return sum(len(chrom.cpg_sites) for chrom in self.chromosomes)

pymethyl2sam/simulator/summary.py

@@ -0,0 +1,67 @@
+from collections import defaultdict
+from typing import Dict, Any, Set, Tuple
+
+from pysam import SamtoolsError
+from pysam.libcalignmentfile import AlignmentFile
+
+from pymethyl2sam.utils import setup_logging
+from pymethyl2sam.utils.pysam import get_read_to_reference_mapping, ReadPosition
+
+logger = setup_logging(__name__)
+
+
+def get_simulation_summary(bam_path: str) -> Dict[str, Any]:
+    stats: Dict[str, Any] = {
+        "total_reads": 0,
+        "reads_with_methylation": 0,
+        "chromosome_count": 0,
+        "regions_per_chromosome": defaultdict(int),
+        "total_methylation_sites": 0,
+    }
+
+    methylation_sites: Set[Tuple[str, int]] = set()
+
+    logger.info(f"Opening BAM file: {bam_path}")
+
+    try:
+        with AlignmentFile(bam_path, "rb") as bamfile:
+            chromosomes: Set[str] = set()
+            logger.info("Processing reads...")
+
+            for read in bamfile.fetch(until_eof=True):
+                reverse_strand_offset = 1 if read.is_reverse else 0
+                stats["total_reads"] += 1
+
+                if read.is_unmapped:
+                    continue
+
+                chrom = bamfile.get_reference_name(read.reference_id)
+                chromosomes.add(chrom)
+                stats["regions_per_chromosome"][chrom] += 1
+
+                if read.has_tag("MM") and read.modified_bases:
+                    read2ref = get_read_to_reference_mapping(read)
+                    stats["reads_with_methylation"] += 1
+
+                    modified_read_positions: Set[ReadPosition] = {
+                        pos - reverse_strand_offset
+                        for mods in read.modified_bases.values()
+                        for pos, _ in mods
+                    }
+
+                    for pos in modified_read_positions:
+                        if pos in read2ref:
+                            methylation_sites.add((chrom, read2ref[pos]))
+
+            stats["total_methylation_sites"] = len(methylation_sites)
+            stats["chromosome_count"] = len(chromosomes)
+            logger.info("Finished processing BAM file.")
+
+    except (FileNotFoundError, PermissionError) as io_err:
+        logger.error(f"File error: {bam_path}", exc_info=io_err)
+    except (ValueError, TypeError, KeyError, AttributeError) as data_err:
+        logger.error("Data format or logic error while parsing BAM.", exc_info=data_err)
+    except (SamtoolsError, EOFError) as bam_err:
+        logger.error("BAM file appears corrupted or unreadable.", exc_info=bam_err)
+
+    return stats

pymethyl2sam/utils/__init__.py

@@ -0,0 +1,6 @@
+"""Logging, constants, shared helpers."""
+
+from .constants import *
+from .logging import setup_logging
+
+__all__ = ["setup_logging"]

pymethyl2sam/utils/constants.py

@@ -0,0 +1,55 @@
+"""Constants used throughout the package."""
+
+from typing import Dict
+
+_ORIG_BASES = "ACGTacgt"
+_COMP_BASES = "TGCAtgca"
+COMPLEMENT_TABLE: Dict[int, int] = str.maketrans(_ORIG_BASES, _COMP_BASES)
+
+INSTRUMENT = "A00000"
+RUN_NUMBER = 1
+FLOWCELL_ID = "ABCD1234"
+
+# Strand orientations
+STRANDS = ["+", "-"]
+
+# SAM/BAM tag names
+MM_TAG = "MM"  # Methylation modification
+ML_TAG = "ML"  # Methylation level
+
+# Default values
+DEFAULT_COVERAGE = 10.0
+DEFAULT_READ_LENGTH = 100
+DEFAULT_ERROR_RATE = 0.005
+DEFAULT_METHYLATION_RATIO = 0.7
+DEFAULT_BASE_QUALITY = 30
+
+# File extensions
+SUPPORTED_GENOME_FORMATS = [".fasta", ".fa", ".fna"]
+SUPPORTED_TEMPLATE_FORMATS = [".yaml", ".yml", ".json"]
+SUPPORTED_CONFIG_FORMATS = [".yaml", ".yml", ".json"]
+
+# Coordinate system
+COORDINATE_SYSTEM = "zero-based"
+INTERVAL_FORMAT = "half-open"  # [start, end)
+
+# Error types
+ERROR_TYPES = ["mismatch", "insertion", "deletion"]
+
+# Quality score ranges
+MIN_QUALITY_SCORE = 0
+MAX_QUALITY_SCORE = 93
+
+# SAM/BAM flags
+SAM_FLAG_PAIRED = 1
+SAM_FLAG_PROPER_PAIR = 2
+SAM_FLAG_UNMAP = 4
+SAM_FLAG_MUNMAP = 8
+SAM_FLAG_REVERSE = 16
+SAM_FLAG_MREVERSE = 32
+SAM_FLAG_READ1 = 64
+SAM_FLAG_READ2 = 128
+SAM_FLAG_SECONDARY = 256
+SAM_FLAG_QCFAIL = 512
+SAM_FLAG_DUP = 1024
+SAM_FLAG_SUPPLEMENTARY = 2048

pymethyl2sam/utils/logging.py

@@ -0,0 +1,60 @@
+"""Logging setup and configuration."""
+
+import logging
+import sys
+from typing import Optional
+
+
+def setup_logging(name: str, level: str = "INFO") -> logging.Logger:
+    """Setup logging for a module.
+
+    Args:
+        name: Logger name (usually __name__)
+        level: Logging level
+
+    Returns:
+        Configured logger
+    """
+    logger = logging.getLogger(name)
+
+    # Avoid adding handlers multiple times
+    if logger.handlers:
+        return logger
+
+    # Set log level
+    logger.setLevel(getattr(logging, level.upper()))
+
+    # Create console handler
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setLevel(getattr(logging, level.upper()))
+
+    # Create formatter
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    handler.setFormatter(formatter)
+
+    # Add handler to logger
+    logger.addHandler(handler)
+
+    return logger
+
+
+def configure_logging(level: str = "INFO", log_file: Optional[str] = None):
+    """Configure global logging.
+
+    Args:
+        level: Logging level
+        log_file: Optional log file path
+    """
+    # Configure root logger
+    logging.basicConfig(
+        level=getattr(logging, level.upper()),
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        handlers=[
+            logging.StreamHandler(sys.stdout),
+            logging.FileHandler(log_file) if log_file else logging.NullHandler(),
+        ],
+    )

pymethyl2sam/utils/pysam.py

@@ -0,0 +1,96 @@
+from random import randint
+from typing import List, Dict
+from typing import Tuple, Set
+
+from pysam.libcalignedsegment import AlignedSegment
+from pysam.libcutils import qualities_to_qualitystring
+
+from . import COMPLEMENT_TABLE, RUN_NUMBER, INSTRUMENT, FLOWCELL_ID
+from ..core.genomics import MethylationSite
+from ..core.sequencing import ReadQuality
+
+ReadPosition = ReferencePosition = int
+AlignedPairs = List[Tuple[ReadPosition, ReferencePosition]]
+
+
+def get_read_to_reference_mapping(read: AlignedSegment):
+    pairs: AlignedPairs = read.get_aligned_pairs(matches_only=False)
+    return {read_pos: ref if ref else None for read_pos, ref in pairs}
+
+
+def make_sam_dict(
+    chrome: str,
+    sequence: str,
+    start: int,
+    is_reverse: bool,
+    quality: ReadQuality,
+) -> Dict[str, str]:
+    read_name = _generate_read_name()
+    read_length = len(sequence)
+    flag = 16 if is_reverse else 0
+    ref_pos = start + 1
+    qual = qualities_to_qualitystring([quality.sequencing_score] * read_length)
+    return {
+        "name": read_name,
+        "flag": str(flag),
+        "ref_name": chrome,
+        "ref_pos": str(ref_pos),
+        "next_ref_name": "*",
+        "next_ref_pos": "0",
+        "map_quality": str(quality.mapping_score),
+        "length": "0",
+        "cigar": f"{read_length}M",
+        "seq": sequence,
+        "qual": qual,
+    }
+
+
+def _generate_read_name() -> str:
+    lane = randint(1, 4)
+    tile = randint(1101, 1200)
+    x_pos = randint(0, 3000)
+    y_pos = randint(0, 3000)
+
+    return (
+        f"{INSTRUMENT}:"
+        f"{RUN_NUMBER:03d}:"  # 3-digit zero padded
+        f"{FLOWCELL_ID}:"
+        f"{lane}:"
+        f"{tile:04d}:"  # 4-digit zero padded
+        f"{x_pos:04d}:"
+        f"{y_pos:04d}"
+    )
+
+
+def generate_mm_tag(
+    fw_sequence: str, methylated_sites: Set[MethylationSite], is_reverse_strand: bool
+) -> str:
+    """
+    Generates a SAM MM tag for methylation.
+    """
+    target_base = "C"
+    strand_tag = "+" if not is_reverse_strand else "-"
+    sequence = (
+        fw_sequence.translate(COMPLEMENT_TABLE)[::-1]
+        if is_reverse_strand
+        else fw_sequence
+    )
+    transform_pos = (
+        (lambda x: len(sequence) - 1 - x) if is_reverse_strand else lambda x: x
+    )
+    methylated_positions = set(
+        transform_pos(site.get_cytosine_position(is_reverse_strand))
+        for site in methylated_sites
+    )
+
+    candidate_positions = (i for i, char in enumerate(sequence) if char == target_base)
+
+    offsets = []
+    last_methyl_idx = -1
+    for candidate_idx, pos in enumerate(candidate_positions):
+        if pos in methylated_positions:
+            offsets.append(candidate_idx - last_methyl_idx - 1)
+            last_methyl_idx = candidate_idx
+            methylated_positions.remove(pos)
+
+    return f"{target_base}{strand_tag}m,{','.join(map(str, offsets))};"