trace-crispr 0.1.0__tar.gz

trace_crispr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin R. Roy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trace_crispr-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: trace-crispr
+Version: 0.1.0
+Summary: TRACE: Triple-aligner Read Analysis for CRISPR Editing
+Author-email: "Kevin R. Roy" <kevinroy@stanford.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/k-roy/trace
+Project-URL: Documentation, https://trace-crispr.readthedocs.io
+Project-URL: Repository, https://github.com/k-roy/trace
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: pysam>=0.20
+Requires-Dist: pandas>=1.5
+Requires-Dist: numpy>=1.20
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rapidfuzz>=3.0
+Requires-Dist: tqdm>=4.60
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: visualization
+Requires-Dist: matplotlib>=3.5; extra == "visualization"
+Requires-Dist: seaborn>=0.12; extra == "visualization"
+Dynamic: license-file
+
+# TRACE
+
+**T**riple-aligner **R**ead **A**nalysis for **C**RISPR **E**diting
+
+## Features
+
+- **Triple-aligner consensus**: Uses BWA-MEM, BBMap, and minimap2 for robust alignment
+- **Automatic inference**: Detects PAM, cleavage site, homology arms, and edits from sequences
+- **K-mer classification**: Fast pre-alignment HDR/WT detection using 12-mers
+- **Multi-nuclease support**: Cas9 and Cas12a (Cpf1) with correct cleavage geometry
+- **Auto-detection**: Library type (TruSeq/Tn5), read merging need, CRISPResso mode
+- **CRISPResso2 integration**: Validation with standard CRISPR analysis tool
+
+## Installation
+
+### pip (Python package only)
+
+```bash
+pip install trace-crispr
+```
+
+### conda (includes external aligners)
+
+```bash
+conda install -c bioconda -c conda-forge trace-crispr
+```
+
+### Development installation
+
+```bash
+git clone https://github.com/k-roy/trace.git
+cd trace
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Minimal run (3 required inputs)
+
+```bash
+trace run \
+  --reference amplicon.fasta \
+  --hdr-template hdr_template.fasta \
+  --guide GCTGAAGCACTGCACGCCGT \
+  --r1 sample_R1.fastq.gz \
+  --r2 sample_R2.fastq.gz \
+  --output results/
+```
+
+### Check locus configuration without running
+
+```bash
+trace info \
+  --reference amplicon.fasta \
+  --hdr-template hdr_template.fasta \
+  --guide GCTGAAGCACTGCACGCCGT
+```
+
+This will print:
+
+```
+=== TRACE Analysis Configuration ===
+
+Reference sequence: 500 bp
+HDR template: 500 bp
+
+Donor template analysis:
+  - Left homology arm: positions 1-245 on reference (245 bp)
+  - Right homology arm: positions 255-500 on reference (245 bp)
+  - Donor edits detected at positions: 246, 247 on reference
+    * Position 246: C → G (PAM-silencing mutation)
+    * Position 247: C → T (chromophore Y66H mutation)
+
+Guide analysis:
+  - Guide sequence: GCTGAAGCACTGCACGCCGT
+  - Guide targets: positions 248-267 on reference (- strand)
+  - PAM: GGG at positions 245-247 on reference
+  - Cleavage site: position 248 on reference
+```
+
+### Multiple samples
+
+Create a sample key TSV:
+
+```
+sample_id	r1_path	r2_path	condition
+sample_1	/path/to/S1_R1.fastq.gz	/path/to/S1_R2.fastq.gz	treatment
+sample_2	/path/to/S2_R1.fastq.gz	/path/to/S2_R2.fastq.gz	control
+```
+
+Then run:
+
+```bash
+trace run \
+  --reference amplicon.fasta \
+  --hdr-template hdr_template.fasta \
+  --guide GCTGAAGCACTGCACGCCGT \
+  --sample-key samples.tsv \
+  --output results/ \
+  --threads 16
+```
+
+### Using Cas12a
+
+```bash
+trace run \
+  --reference amplicon.fasta \
+  --hdr-template hdr_template.fasta \
+  --guide GCTGAAGCACTGCACGCCGTAA \
+  --nuclease cas12a \
+  --sample-key samples.tsv \
+  --output results/
+```
+
+## Nuclease Support
+
+### Cas9 (SpCas9)
+- PAM: NGG (3' of protospacer)
+- Cleavage: 3 bp upstream of PAM (blunt ends)
+
+### Cas12a (LbCpf1)
+- PAM: TTTN (5' of protospacer)
+- Cleavage: 18-19 bp downstream on target strand, 23 bp on non-target
+- Creates 4-5 nt 5' overhang (staggered cut)
+
+## Output
+
+The main output is a TSV file with per-sample editing outcomes:
+
+| Column | Description |
+|--------|-------------|
+| sample | Sample ID |
+| classifiable_reads | Total classifiable reads |
+| duplicate_rate | PCR duplicate rate (Tn5) |
+| Dedup_WT_% | Wild-type % (deduplicated) |
+| Dedup_HDR_% | HDR % (deduplicated) |
+| Dedup_NHEJ_% | NHEJ % (deduplicated) |
+| Dedup_LgDel_% | Large deletion % |
+| kmer_hdr_rate | K-mer method HDR rate |
+| crispresso_hdr_rate | CRISPResso2 HDR rate |
+
+## Dependencies
+
+### Python
+- click>=8.0
+- pysam>=0.20
+- pandas>=1.5
+- numpy>=1.20
+- pyyaml>=6.0
+- rapidfuzz>=3.0
+- tqdm>=4.60
+
+### External tools (via conda)
+- bwa>=0.7
+- bbmap>=39
+- minimap2>=2.24
+- samtools>=1.16
+- crispresso2 (optional, but enabled by default)
+
+## Author
+
+Kevin R. Roy
+
+## License
+
+MIT

trace_crispr-0.1.0/README.md

@@ -0,0 +1,166 @@
+# TRACE
+
+**T**riple-aligner **R**ead **A**nalysis for **C**RISPR **E**diting
+
+## Features
+
+- **Triple-aligner consensus**: Uses BWA-MEM, BBMap, and minimap2 for robust alignment
+- **Automatic inference**: Detects PAM, cleavage site, homology arms, and edits from sequences
+- **K-mer classification**: Fast pre-alignment HDR/WT detection using 12-mers
+- **Multi-nuclease support**: Cas9 and Cas12a (Cpf1) with correct cleavage geometry
+- **Auto-detection**: Library type (TruSeq/Tn5), read merging need, CRISPResso mode
+- **CRISPResso2 integration**: Validation with standard CRISPR analysis tool
+
+## Installation
+
+### pip (Python package only)
+
+```bash
+pip install trace-crispr
+```
+
+### conda (includes external aligners)
+
+```bash
+conda install -c bioconda -c conda-forge trace-crispr
+```
+
+### Development installation
+
+```bash
+git clone https://github.com/k-roy/trace.git
+cd trace
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Minimal run (3 required inputs)
+
+```bash
+trace run \
+  --reference amplicon.fasta \
+  --hdr-template hdr_template.fasta \
+  --guide GCTGAAGCACTGCACGCCGT \
+  --r1 sample_R1.fastq.gz \
+  --r2 sample_R2.fastq.gz \
+  --output results/
+```
+
+### Check locus configuration without running
+
+```bash
+trace info \
+  --reference amplicon.fasta \
+  --hdr-template hdr_template.fasta \
+  --guide GCTGAAGCACTGCACGCCGT
+```
+
+This will print:
+
+```
+=== TRACE Analysis Configuration ===
+
+Reference sequence: 500 bp
+HDR template: 500 bp
+
+Donor template analysis:
+  - Left homology arm: positions 1-245 on reference (245 bp)
+  - Right homology arm: positions 255-500 on reference (245 bp)
+  - Donor edits detected at positions: 246, 247 on reference
+    * Position 246: C → G (PAM-silencing mutation)
+    * Position 247: C → T (chromophore Y66H mutation)
+
+Guide analysis:
+  - Guide sequence: GCTGAAGCACTGCACGCCGT
+  - Guide targets: positions 248-267 on reference (- strand)
+  - PAM: GGG at positions 245-247 on reference
+  - Cleavage site: position 248 on reference
+```
+
+### Multiple samples
+
+Create a sample key TSV:
+
+```
+sample_id	r1_path	r2_path	condition
+sample_1	/path/to/S1_R1.fastq.gz	/path/to/S1_R2.fastq.gz	treatment
+sample_2	/path/to/S2_R1.fastq.gz	/path/to/S2_R2.fastq.gz	control
+```
+
+Then run:
+
+```bash
+trace run \
+  --reference amplicon.fasta \
+  --hdr-template hdr_template.fasta \
+  --guide GCTGAAGCACTGCACGCCGT \
+  --sample-key samples.tsv \
+  --output results/ \
+  --threads 16
+```
+
+### Using Cas12a
+
+```bash
+trace run \
+  --reference amplicon.fasta \
+  --hdr-template hdr_template.fasta \
+  --guide GCTGAAGCACTGCACGCCGTAA \
+  --nuclease cas12a \
+  --sample-key samples.tsv \
+  --output results/
+```
+
+## Nuclease Support
+
+### Cas9 (SpCas9)
+- PAM: NGG (3' of protospacer)
+- Cleavage: 3 bp upstream of PAM (blunt ends)
+
+### Cas12a (LbCpf1)
+- PAM: TTTN (5' of protospacer)
+- Cleavage: 18-19 bp downstream on target strand, 23 bp on non-target
+- Creates 4-5 nt 5' overhang (staggered cut)
+
+## Output
+
+The main output is a TSV file with per-sample editing outcomes:
+
+| Column | Description |
+|--------|-------------|
+| sample | Sample ID |
+| classifiable_reads | Total classifiable reads |
+| duplicate_rate | PCR duplicate rate (Tn5) |
+| Dedup_WT_% | Wild-type % (deduplicated) |
+| Dedup_HDR_% | HDR % (deduplicated) |
+| Dedup_NHEJ_% | NHEJ % (deduplicated) |
+| Dedup_LgDel_% | Large deletion % |
+| kmer_hdr_rate | K-mer method HDR rate |
+| crispresso_hdr_rate | CRISPResso2 HDR rate |
+
+## Dependencies
+
+### Python
+- click>=8.0
+- pysam>=0.20
+- pandas>=1.5
+- numpy>=1.20
+- pyyaml>=6.0
+- rapidfuzz>=3.0
+- tqdm>=4.60
+
+### External tools (via conda)
+- bwa>=0.7
+- bbmap>=39
+- minimap2>=2.24
+- samtools>=1.16
+- crispresso2 (optional, but enabled by default)
+
+## Author
+
+Kevin R. Roy
+
+## License
+
+MIT

trace_crispr-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trace-crispr"
+version = "0.1.0"
+description = "TRACE: Triple-aligner Read Analysis for CRISPR Editing"
+readme = "README.md"
+license = "MIT"
+authors = [{name = "Kevin R. Roy", email = "kevinroy@stanford.edu"}]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "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",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "click>=8.0",
+    "pysam>=0.20",
+    "pandas>=1.5",
+    "numpy>=1.20",
+    "pyyaml>=6.0",
+    "rapidfuzz>=3.0",
+    "tqdm>=4.60",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "black",
+    "ruff",
+    "mypy",
+]
+visualization = [
+    "matplotlib>=3.5",
+    "seaborn>=0.12",
+]
+
+[project.scripts]
+trace = "trace_crispr.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/k-roy/trace"
+Documentation = "https://trace-crispr.readthedocs.io"
+Repository = "https://github.com/k-roy/trace"
+
+[tool.setuptools.packages.find]
+where = ["."]
+
+[tool.setuptools.package-data]
+trace_crispr = ["templates/*"]
+
+[tool.black]
+line-length = 100
+target-version = ['py39', 'py310', 'py311']
+
+[tool.ruff]
+line-length = 100
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true

trace_crispr-0.1.0/setup.cfg

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

trace_crispr-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for CRISPRo."""

trace_crispr-0.1.0/tests/test_config.py

@@ -0,0 +1,129 @@
+"""Tests for trace.config module."""
+
+import pytest
+from trace_crispr.config import LocusConfig, NucleaseType
+
+
+# BFP/GFP test sequences
+BFP_REFERENCE = (
+    "TGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACC"
+    "CACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCC"
+    "CGAAGGCTACGTCCAGGAGCGCACCAT"
+)
+
+GFP_HDR_TEMPLATE = (
+    "TGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACG"
+    "TACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCC"
+    "CGAAGGCTACGTCCAGGAGCGCACCAT"
+)
+
+GUIDE_SEQUENCE = "GCTGAAGCACTGCACGCCGT"
+
+
+class TestLocusConfig:
+    """Test LocusConfig class."""
+
+    def test_basic_initialization(self):
+        """Test basic LocusConfig creation."""
+        locus = LocusConfig(
+            name="test",
+            reference=BFP_REFERENCE,
+            hdr_template=GFP_HDR_TEMPLATE,
+            guide=GUIDE_SEQUENCE,
+            nuclease=NucleaseType.CAS9,
+        )
+
+        assert locus.name == "test"
+        assert locus.reference == BFP_REFERENCE
+        assert locus.hdr_template == GFP_HDR_TEMPLATE
+        assert locus.guide == GUIDE_SEQUENCE
+        assert locus.nuclease == NucleaseType.CAS9
+
+    def test_analyze_detects_edits(self):
+        """Test that analyze() detects HDR edits."""
+        locus = LocusConfig(
+            name="test",
+            reference=BFP_REFERENCE,
+            hdr_template=GFP_HDR_TEMPLATE,
+            guide=GUIDE_SEQUENCE,
+            nuclease=NucleaseType.CAS9,
+        ).analyze()
+
+        assert locus.edits is not None
+        assert len(locus.edits) == 2
+
+        # Check edit positions (0-indexed: 70, 71)
+        edit_positions = [e.position for e in locus.edits]
+        assert 70 in edit_positions
+        assert 71 in edit_positions
+
+    def test_analyze_detects_homology_arms(self):
+        """Test that analyze() detects homology arms."""
+        locus = LocusConfig(
+            name="test",
+            reference=BFP_REFERENCE,
+            hdr_template=GFP_HDR_TEMPLATE,
+            guide=GUIDE_SEQUENCE,
+            nuclease=NucleaseType.CAS9,
+        ).analyze()
+
+        assert locus.homology_arms is not None
+        assert locus.homology_arms.left_start == 0
+        assert locus.homology_arms.left_end == 70  # First edit at position 70
+
+    def test_analyze_finds_guide_on_minus_strand(self):
+        """Test that analyze() finds the guide on the minus strand."""
+        locus = LocusConfig(
+            name="test",
+            reference=BFP_REFERENCE,
+            hdr_template=GFP_HDR_TEMPLATE,
+            guide=GUIDE_SEQUENCE,
+            nuclease=NucleaseType.CAS9,
+        ).analyze()
+
+        assert locus.guide_info is not None
+        assert locus.guide_info.strand == '-'
+        # Guide is on minus strand, so PAM is upstream
+
+    def test_analyze_calculates_cleavage_site(self):
+        """Test that analyze() calculates cleavage site for Cas9."""
+        locus = LocusConfig(
+            name="test",
+            reference=BFP_REFERENCE,
+            hdr_template=GFP_HDR_TEMPLATE,
+            guide=GUIDE_SEQUENCE,
+            nuclease=NucleaseType.CAS9,
+        ).analyze()
+
+        assert locus.guide_info is not None
+        # Cleavage site should be within reasonable distance of guide
+        assert locus.guide_info.cleavage_site > 0
+
+    def test_guide_not_found_raises_error(self):
+        """Test that analyze() raises error when guide not found."""
+        locus = LocusConfig(
+            name="test",
+            reference=BFP_REFERENCE,
+            hdr_template=GFP_HDR_TEMPLATE,
+            guide="NNNNNNNNNNNNNNNNNNNN",  # Non-existent guide
+            nuclease=NucleaseType.CAS9,
+        )
+
+        with pytest.raises(ValueError, match="not found"):
+            locus.analyze()
+
+
+class TestNucleaseType:
+    """Test NucleaseType enum."""
+
+    def test_cas9_value(self):
+        """Test Cas9 enum value."""
+        assert NucleaseType.CAS9.value == "cas9"
+
+    def test_cas12a_value(self):
+        """Test Cas12a enum value."""
+        assert NucleaseType.CAS12A.value == "cas12a"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])