pymethyl2sam 0.1.2__tar.gz

pymethyl2sam-0.1.2/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: pymethyl2sam
+Version: 0.1.2
+Summary: Simulate DNA methylation and generate synthetic NGS reads with methylation tags.
+Author-email: Yoni Weissler <yoni.weissler@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yoni-w/pymethyl2sam
+Project-URL: Repository, https://github.com/yoni-w/pymethyl2sam
+Project-URL: Documentation, https://pymethyl2sam.readthedocs.io
+Project-URL: Issues, https://github.com/yoni-w/pymethyl2sam/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pysam>=0.21.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: importlib-metadata>=8.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: pylint>=3.2.0; extra == "dev"
+Requires-Dist: pre-commit>=3.2.0; extra == "dev"
+Requires-Dist: sphinx>=6.0.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "dev"
+Requires-Dist: coverage[toml]>=7.0.0; extra == "dev"
+
+# pymethyl2sam
+
+A Python package for simulating DNA methylation and generating synthetic NGS reads with methylation tags (MM/ML) in SAM/BAM format.
+
+## Overview
+
+pymethyl2sam provides a comprehensive framework for simulating DNA methylation patterns and generating synthetic next-generation sequencing reads with proper methylation tags. The package supports both stochastic (random) and deterministic (pattern-based) read generation modes, making it suitable for testing methylation analysis pipelines and educational purposes.
+
+## Features
+
+- **Dual Read Generation Modes**: Random (stochastic) and pattern-based (deterministic) simulation
+- **Flexible Methylation Modeling**: Support for fully, partially, or unmethylated sites
+- **Valid SAM/BAM Output**: Generates properly formatted files with MM/ML methylation tags
+- **Configurable Parameters**: Coverage, read length, error rates, strand bias
+- **Zero-based Coordinates**: Consistent with bioinformatics conventions
+- **Extensible Architecture**: Modular, layered design for easy extension
+
+## Installation
+
+### From PyPI (when available)
+```bash
+pip install pymethyl2sam
+```
+
+### From Source
+```bash
+git clone https://github.com/yoni-w/pymethyl2sam.git
+cd pymethyl2sam
+pip install -e .
+```
+
+### Development Installation
+```bash
+git clone https://github.com/yoni-w/pymethyl2sam.git
+cd pymethyl2sam
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Basic Usage (Random Mode)
+
+```python
+from pymethyl2sam import MethylationSimulator
+from pymethyl2sam.core import MethylationSite
+from pymethyl2sam.core.genomics import StrandOrientation
+from pymethyl2sam.core.reference_genome import Hg38ReferenceGenome
+from pymethyl2sam.core.sequencing import ReadGenerator, RandomStrategy
+from pymethyl2sam.simulator import SequencedChromosome, SequencedRegion
+
+# Create simulator with random read generation
+simulator = MethylationSimulator(
+    chromosomes=[
+        SequencedChromosome(
+            name="chr1",
+            length=20_000,
+            regions=[
+                SequencedRegion(
+                    start=10100,
+                    end=10450,
+                    read_generator=ReadGenerator(strategy=RandomStrategy()),
+                )
+            ],
+            cpg_sites=[
+                MethylationSite(position=10100, methylation_prob=1.0),
+                MethylationSite(position=10149, methylation_prob=1.0),
+                MethylationSite(position=10155, methylation_prob=0.0),
+                MethylationSite(position=10200, methylation_prob=0.0),
+                MethylationSite(position=10220, methylation_prob=1.0),
+            ],
+        )
+    ],
+    reference_genome=Hg38ReferenceGenome(),
+)
+
+# Generate reads and write to BAM
+simulator.simulate_reads("output.bam")
+```
+
+### Pattern-Based Simulation
+
+```python
+from pymethyl2sam import MethylationSimulator
+from pymethyl2sam.core import MethylationSite
+from pymethyl2sam.core.genomics import StrandOrientation
+from pymethyl2sam.core.reference_genome import Hg38ReferenceGenome
+from pymethyl2sam.core.sequencing import ReadGenerator, PatternStrategy
+from pymethyl2sam.simulator import SequencedChromosome, SequencedRegion
+
+# Create simulator with pattern-based read generation
+simulator = MethylationSimulator(
+    chromosomes=[
+        SequencedChromosome(
+            name="chr1",
+            length=20_000,
+            regions=[
+                SequencedRegion(
+                    start=10100,
+                    end=10250,
+                    read_generator=ReadGenerator(
+                        read_length=150,
+                        strategy=PatternStrategy.from_offsets(
+                            offsets=[0] * 10,
+                            orientation=StrandOrientation.RANDOM,
+                        ),
+                    ),
+                )
+            ],
+            cpg_sites=[
+                MethylationSite(position=10100, methylation_prob=1.0),
+                MethylationSite(position=10149, methylation_prob=1.0),
+                MethylationSite(position=10155, methylation_prob=0.0),
+                MethylationSite(position=10200, methylation_prob=0.0),
+                MethylationSite(position=10220, methylation_prob=1.0),
+            ],
+        )
+    ],
+    reference_genome=Hg38ReferenceGenome(),
+)
+
+# Generate reads and write to BAM
+simulator.simulate_reads("pattern_output.bam")
+```
+
+## Architecture
+
+The package is organized in layers by functional responsibility:
+
+- **core/**: Domain logic for methylation modeling, sequencing, and errors
+- **simulator/**: Orchestration of read and methylation simulation
+- **io/**: Parsers and I/O for FASTA, BED, YAML, JSON
+- **utils/**: Logging, constants, shared helpers
+
+### Core Components
+
+- `MethylationSimulator`: Main class for orchestrating simulation
+- `SequencedChromosome`: Represents a chromosome with defined regions and methylation sites
+- `SequencedRegion`: Defines genomic regions where reads should be generated
+- `ReadGenerator`: Handles read generation with different strategies (Random/Pattern)
+- `MethylationSite`: Represents individual methylation sites with probabilities
+- `ReferenceGenomeProvider`: Interface for accessing reference genome sequences
+
+## Configuration Examples
+
+### YAML Configuration Files
+
+See `examples/config_random.yaml` and `examples/templates_pattern.yaml` for configuration file examples.
+
+## Coordinate System
+
+All genomic coordinates follow zero-based, half-open intervals `[start, end)`:
+
+- A 5-base interval starting at position 100 is `[100, 105)`
+- Read coordinates and methylation positions adhere to this system
+- MM/ML tags follow strand-specific SAM/BAM conventions
+
+## Testing
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+Run with coverage:
+
+```bash
+pytest --cov=pymethyl2sam --cov-report=html
+```
+
+## Development
+
+### Code Formatting
+
+```bash
+black src/ tests/
+```
+
+### Linting
+
+```bash
+pylint src/pymethyl2sam/
+```
+
+### Pre-commit Hooks
+
+```bash
+pre-commit install
+```
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `simulate_cpgs.py`: Demonstrates both random and pattern-based simulation
+- `config_random.yaml`: YAML configuration for random mode
+- `templates_pattern.yaml`: YAML template for pattern-based simulation
+
+## Documentation
+
+For detailed API documentation, visit: https://pymethyl2sam.readthedocs.io
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass
+6. Submit a pull request
+
+## Citation
+
+If you use pymethyl2sam in your research, please cite:
+
+```
+pymethyl2sam: A Python package for simulating DNA methylation and generating synthetic NGS reads
+Yoni Weissler, 2025
+```
+
+## Support
+
+- **Issues**: https://github.com/yoni-w/pymethyl2sam/issues
+- **Documentation**: https://pymethyl2sam.readthedocs.io
+- **Email**: yoni.weissler@gmail.com

pymethyl2sam-0.1.2/README.md

@@ -0,0 +1,229 @@
+# pymethyl2sam
+
+A Python package for simulating DNA methylation and generating synthetic NGS reads with methylation tags (MM/ML) in SAM/BAM format.
+
+## Overview
+
+pymethyl2sam provides a comprehensive framework for simulating DNA methylation patterns and generating synthetic next-generation sequencing reads with proper methylation tags. The package supports both stochastic (random) and deterministic (pattern-based) read generation modes, making it suitable for testing methylation analysis pipelines and educational purposes.
+
+## Features
+
+- **Dual Read Generation Modes**: Random (stochastic) and pattern-based (deterministic) simulation
+- **Flexible Methylation Modeling**: Support for fully, partially, or unmethylated sites
+- **Valid SAM/BAM Output**: Generates properly formatted files with MM/ML methylation tags
+- **Configurable Parameters**: Coverage, read length, error rates, strand bias
+- **Zero-based Coordinates**: Consistent with bioinformatics conventions
+- **Extensible Architecture**: Modular, layered design for easy extension
+
+## Installation
+
+### From PyPI (when available)
+```bash
+pip install pymethyl2sam
+```
+
+### From Source
+```bash
+git clone https://github.com/yoni-w/pymethyl2sam.git
+cd pymethyl2sam
+pip install -e .
+```
+
+### Development Installation
+```bash
+git clone https://github.com/yoni-w/pymethyl2sam.git
+cd pymethyl2sam
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Basic Usage (Random Mode)
+
+```python
+from pymethyl2sam import MethylationSimulator
+from pymethyl2sam.core import MethylationSite
+from pymethyl2sam.core.genomics import StrandOrientation
+from pymethyl2sam.core.reference_genome import Hg38ReferenceGenome
+from pymethyl2sam.core.sequencing import ReadGenerator, RandomStrategy
+from pymethyl2sam.simulator import SequencedChromosome, SequencedRegion
+
+# Create simulator with random read generation
+simulator = MethylationSimulator(
+    chromosomes=[
+        SequencedChromosome(
+            name="chr1",
+            length=20_000,
+            regions=[
+                SequencedRegion(
+                    start=10100,
+                    end=10450,
+                    read_generator=ReadGenerator(strategy=RandomStrategy()),
+                )
+            ],
+            cpg_sites=[
+                MethylationSite(position=10100, methylation_prob=1.0),
+                MethylationSite(position=10149, methylation_prob=1.0),
+                MethylationSite(position=10155, methylation_prob=0.0),
+                MethylationSite(position=10200, methylation_prob=0.0),
+                MethylationSite(position=10220, methylation_prob=1.0),
+            ],
+        )
+    ],
+    reference_genome=Hg38ReferenceGenome(),
+)
+
+# Generate reads and write to BAM
+simulator.simulate_reads("output.bam")
+```
+
+### Pattern-Based Simulation
+
+```python
+from pymethyl2sam import MethylationSimulator
+from pymethyl2sam.core import MethylationSite
+from pymethyl2sam.core.genomics import StrandOrientation
+from pymethyl2sam.core.reference_genome import Hg38ReferenceGenome
+from pymethyl2sam.core.sequencing import ReadGenerator, PatternStrategy
+from pymethyl2sam.simulator import SequencedChromosome, SequencedRegion
+
+# Create simulator with pattern-based read generation
+simulator = MethylationSimulator(
+    chromosomes=[
+        SequencedChromosome(
+            name="chr1",
+            length=20_000,
+            regions=[
+                SequencedRegion(
+                    start=10100,
+                    end=10250,
+                    read_generator=ReadGenerator(
+                        read_length=150,
+                        strategy=PatternStrategy.from_offsets(
+                            offsets=[0] * 10,
+                            orientation=StrandOrientation.RANDOM,
+                        ),
+                    ),
+                )
+            ],
+            cpg_sites=[
+                MethylationSite(position=10100, methylation_prob=1.0),
+                MethylationSite(position=10149, methylation_prob=1.0),
+                MethylationSite(position=10155, methylation_prob=0.0),
+                MethylationSite(position=10200, methylation_prob=0.0),
+                MethylationSite(position=10220, methylation_prob=1.0),
+            ],
+        )
+    ],
+    reference_genome=Hg38ReferenceGenome(),
+)
+
+# Generate reads and write to BAM
+simulator.simulate_reads("pattern_output.bam")
+```
+
+## Architecture
+
+The package is organized in layers by functional responsibility:
+
+- **core/**: Domain logic for methylation modeling, sequencing, and errors
+- **simulator/**: Orchestration of read and methylation simulation
+- **io/**: Parsers and I/O for FASTA, BED, YAML, JSON
+- **utils/**: Logging, constants, shared helpers
+
+### Core Components
+
+- `MethylationSimulator`: Main class for orchestrating simulation
+- `SequencedChromosome`: Represents a chromosome with defined regions and methylation sites
+- `SequencedRegion`: Defines genomic regions where reads should be generated
+- `ReadGenerator`: Handles read generation with different strategies (Random/Pattern)
+- `MethylationSite`: Represents individual methylation sites with probabilities
+- `ReferenceGenomeProvider`: Interface for accessing reference genome sequences
+
+## Configuration Examples
+
+### YAML Configuration Files
+
+See `examples/config_random.yaml` and `examples/templates_pattern.yaml` for configuration file examples.
+
+## Coordinate System
+
+All genomic coordinates follow zero-based, half-open intervals `[start, end)`:
+
+- A 5-base interval starting at position 100 is `[100, 105)`
+- Read coordinates and methylation positions adhere to this system
+- MM/ML tags follow strand-specific SAM/BAM conventions
+
+## Testing
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+Run with coverage:
+
+```bash
+pytest --cov=pymethyl2sam --cov-report=html
+```
+
+## Development
+
+### Code Formatting
+
+```bash
+black src/ tests/
+```
+
+### Linting
+
+```bash
+pylint src/pymethyl2sam/
+```
+
+### Pre-commit Hooks
+
+```bash
+pre-commit install
+```
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `simulate_cpgs.py`: Demonstrates both random and pattern-based simulation
+- `config_random.yaml`: YAML configuration for random mode
+- `templates_pattern.yaml`: YAML template for pattern-based simulation
+
+## Documentation
+
+For detailed API documentation, visit: https://pymethyl2sam.readthedocs.io
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass
+6. Submit a pull request
+
+## Citation
+
+If you use pymethyl2sam in your research, please cite:
+
+```
+pymethyl2sam: A Python package for simulating DNA methylation and generating synthetic NGS reads
+Yoni Weissler, 2025
+```
+
+## Support
+
+- **Issues**: https://github.com/yoni-w/pymethyl2sam/issues
+- **Documentation**: https://pymethyl2sam.readthedocs.io
+- **Email**: yoni.weissler@gmail.com

pymethyl2sam-0.1.2/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pymethyl2sam"
+version = "0.1.2"
+description = "Simulate DNA methylation and generate synthetic NGS reads with methylation tags."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Yoni Weissler", email = "yoni.weissler@gmail.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS :: MacOS X"
+]
+requires-python = ">=3.9"
+dependencies = [
+    "pysam>=0.21.0",
+    "numpy>=1.21.0",
+    "pyyaml>=6.0",
+    "click>=8.0.0",
+    "typing-extensions>=4.0.0",
+    "importlib-metadata>=8.7.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "black>=23.0.0",
+    "pylint>=3.2.0",
+    "pre-commit>=3.2.0",
+    "sphinx>=6.0.0",
+    "sphinx-rtd-theme>=1.2.0",
+    "coverage[toml]>=7.0.0"
+]
+
+[project.scripts]
+
+[project.urls]
+Homepage = "https://github.com/yoni-w/pymethyl2sam"
+Repository = "https://github.com/yoni-w/pymethyl2sam"
+Documentation = "https://pymethyl2sam.readthedocs.io"
+Issues = "https://github.com/yoni-w/pymethyl2sam/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 88
+target-version = ["py38"]
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+    \.eggs
+  | \.git
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.pylint.messages_control]
+disable = [
+    "C0114",  # missing-module-docstring
+    "C0115",  # missing-class-docstring
+    "C0116",  # missing-function-docstring
+    "W1203"   # logging-fstring-interpolation
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "--strict-markers",
+    "--strict-config"
+]
+
+[tool.coverage.run]
+branch = true
+source = ["src/pymethyl2sam"]
+omit = [
+    "setup_dev.py",
+    "examples/*",
+    "tests/*",
+]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+skip_covered = true
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:"
+]
+
+[tool.sphinx]
+builder = "html"
+source-dir = "docs"
+build-dir = "docs/_build"

pymethyl2sam-0.1.2/setup.cfg

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

pymethyl2sam-0.1.2/src/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-0.1.2/src/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"]