rectify-rna 2.1.0__py3-none-any.whl

rectify/__init__.py

@@ -0,0 +1,36 @@
+"""
+RECTIFY: Unified RNA 3' End Correction Framework
+
+A modular framework for correcting 3' end mapping artifacts in poly(A)-tailed RNA sequencing data.
+
+Modules:
+- A-tract ambiguity detection (universal)
+- AG mispriming screening (oligo-dT methods)
+- Poly(A) tail trimming and indel correction (direct RNA-seq)
+- NET-seq refinement (optional)
+
+Features (v2.1.0):
+- Region-based parallel BAM processing with coverage gap splitting
+- SLURM-aware CPU detection to prevent oversubscription
+- Streaming output mode for large BAM files
+
+Author: Kevin R. Roy
+License: MIT
+"""
+
+__version__ = "2.1.0"
+__author__ = "Kevin R. Roy"
+__email__ = "kevinroy@stanford.edu"
+
+from . import core, utils, slurm
+from .slurm import get_available_cpus, set_thread_limits, is_slurm_job
+
+__all__ = [
+    "core",
+    "utils",
+    "slurm",
+    "get_available_cpus",
+    "set_thread_limits",
+    "is_slurm_job",
+    "__version__",
+]

rectify/__main__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+"""
+Entry point for running RECTIFY as a module: python -m rectify
+"""
+
+from .cli import main
+
+if __name__ == '__main__':
+    main()

rectify/cli.py

@@ -0,0 +1,376 @@
+#!/usr/bin/env python3
+"""
+RECTIFY command-line interface.
+
+Provides commands for:
+- correct: Correct 3' end positions in BAM files
+- train-polya: Train poly(A) tail model from control data
+- validate: Validate corrections against NET-seq or other ground truth
+
+Author: Kevin R. Roy
+Date: 2026-03-09
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+from . import __version__
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create main argument parser."""
+    parser = argparse.ArgumentParser(
+        prog='rectify',
+        description='RECTIFY: Unified RNA 3\' End Correction Framework',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # QuantSeq (oligo-dT short-read)
+  rectify correct quantseq.bam --genome sacCer3.fa --annotation genes.gtf --polya-sequenced -o corrected.tsv
+
+  # Nanopore direct RNA-seq with NET-seq refinement
+  rectify correct nanopore.bam --genome sacCer3.fa --annotation genes.gtf --polya-sequenced \\
+          --aligner minimap2 --netseq-dir bigwigs/ -o corrected.tsv
+
+  # Train poly(A) model
+  rectify train-polya nanopore.bam --genome sacCer3.fa --control-sites cpa_clusters.tsv -o model.json
+
+Citation:
+  Roy, K. R., & Chanfreau, G. F. (2019). RECTIFY: Identification and correction of mRNA
+  mis-termination caused by oligo(dT)-primed internal priming. Nucleic Acids Research, 47(16), e96.
+        """
+    )
+
+    parser.add_argument(
+        '--version',
+        action='version',
+        version=f'RECTIFY {__version__}'
+    )
+
+    subparsers = parser.add_subparsers(dest='command', help='Available commands')
+
+    # =========================================================================
+    # correct command
+    # =========================================================================
+    correct_parser = subparsers.add_parser(
+        'correct',
+        help='Correct 3\' end positions in BAM file',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter
+    )
+
+    # Required arguments
+    correct_parser.add_argument(
+        'bam',
+        type=Path,
+        help='Input BAM file (aligned RNA-seq reads)'
+    )
+
+    correct_parser.add_argument(
+        '--genome',
+        type=Path,
+        required=True,
+        help='Reference genome FASTA file (indexed with .fai)'
+    )
+
+    correct_parser.add_argument(
+        '-o', '--output',
+        type=Path,
+        required=True,
+        help='Output TSV file with corrected 3\' end positions'
+    )
+
+    # Optional arguments
+    correct_parser.add_argument(
+        '--annotation',
+        type=Path,
+        help='Gene annotation file (GTF/GFF) for AG mispriming context'
+    )
+
+    # Technology flags
+    tech_group = correct_parser.add_argument_group('Technology settings')
+    tech_group.add_argument(
+        '--polya-sequenced',
+        action='store_true',
+        help='Poly(A) tail IS sequenced (enables poly(A) trimming and indel correction). '
+             'Use for: nanopore direct RNA, Helicos, QuantSeq, etc.'
+    )
+
+    tech_group.add_argument(
+        '--aligner',
+        choices=['minimap2', 'bwa', 'star', 'auto'],
+        default='auto',
+        help='Aligner used (affects indel artifact detection)'
+    )
+
+    # Module flags
+    module_group = correct_parser.add_argument_group('Module selection')
+    module_group.add_argument(
+        '--skip-atract-check',
+        action='store_true',
+        help='Skip A-tract ambiguity detection (for organisms without A-tracts)'
+    )
+
+    module_group.add_argument(
+        '--skip-ag-check',
+        action='store_true',
+        help='Skip AG mispriming screening'
+    )
+
+    module_group.add_argument(
+        '--skip-polya-trim',
+        action='store_true',
+        help='Skip poly(A) tail trimming (even if --polya-sequenced)'
+    )
+
+    module_group.add_argument(
+        '--skip-indel-correction',
+        action='store_true',
+        help='Skip indel artifact correction (even if --polya-sequenced)'
+    )
+
+    # Poly(A) model
+    polya_group = correct_parser.add_argument_group('Poly(A) tail model')
+    polya_group.add_argument(
+        '--polya-model',
+        type=Path,
+        help='Pre-trained poly(A) tail model (JSON). If not provided, uses built-in model.'
+    )
+
+    # NET-seq refinement
+    netseq_group = correct_parser.add_argument_group('NET-seq refinement')
+    netseq_group.add_argument(
+        '--netseq-dir',
+        type=Path,
+        help='Directory containing NET-seq BigWig files (.bw) for refinement'
+    )
+
+    netseq_group.add_argument(
+        '--netseq-samples',
+        nargs='+',
+        help='NET-seq sample names to use (e.g., wt_2022_rep1). If not provided, auto-detect.'
+    )
+
+    # Thresholds and parameters
+    param_group = correct_parser.add_argument_group('Parameters')
+    param_group.add_argument(
+        '--ag-threshold',
+        type=float,
+        default=0.65,
+        help='AG-richness threshold for mispriming flagging (0.0-1.0)'
+    )
+
+    param_group.add_argument(
+        '--polya-richness',
+        type=float,
+        default=0.8,
+        help='A-richness threshold for poly(A) tail detection (0.0-1.0)'
+    )
+
+    param_group.add_argument(
+        '--min-polya-length',
+        type=int,
+        default=15,
+        help='Minimum poly(A) tail length for nanopore oligo-dT priming'
+    )
+
+    # Output options
+    output_group = correct_parser.add_argument_group('Output options')
+    output_group.add_argument(
+        '--report',
+        type=Path,
+        help='Output QC report file (HTML or PDF)'
+    )
+
+    output_group.add_argument(
+        '--verbose',
+        action='store_true',
+        help='Verbose logging'
+    )
+
+    # Performance options
+    perf_group = correct_parser.add_argument_group('Performance options')
+    perf_group.add_argument(
+        '-j', '--threads',
+        type=int,
+        default=0,
+        help='Number of threads for parallel processing. '
+             '0 = auto-detect from SLURM_CPUS_PER_TASK or system (default: 0)'
+    )
+
+    perf_group.add_argument(
+        '--streaming',
+        action='store_true',
+        help='Use streaming output mode to minimize memory usage. '
+             'Recommended for BAM files > 10GB. Writes directly to output file.'
+    )
+
+    perf_group.add_argument(
+        '--chunk-size',
+        type=int,
+        default=10000,
+        help='Number of reads per output chunk in streaming mode (default: 10000)'
+    )
+
+    # =========================================================================
+    # train-polya command
+    # =========================================================================
+    train_parser = subparsers.add_parser(
+        'train-polya',
+        help='Train poly(A) tail model from control data',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter
+    )
+
+    train_parser.add_argument(
+        'bam',
+        type=Path,
+        help='Input BAM file with soft-clipped poly(A) tails'
+    )
+
+    train_parser.add_argument(
+        '--genome',
+        type=Path,
+        required=True,
+        help='Reference genome FASTA file'
+    )
+
+    train_parser.add_argument(
+        '--control-sites',
+        type=Path,
+        required=True,
+        help='TSV file with control CPA sites (0A downstream A-count)'
+    )
+
+    train_parser.add_argument(
+        '-o', '--output',
+        type=Path,
+        required=True,
+        help='Output model file (JSON)'
+    )
+
+    train_parser.add_argument(
+        '--min-reads',
+        type=int,
+        default=10,
+        help='Minimum reads per control site for training'
+    )
+
+    train_parser.add_argument(
+        '--verbose',
+        action='store_true',
+        help='Verbose logging'
+    )
+
+    # =========================================================================
+    # validate command
+    # =========================================================================
+    validate_parser = subparsers.add_parser(
+        'validate',
+        help='Validate corrections against ground truth',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter
+    )
+
+    # Required arguments
+    validate_parser.add_argument(
+        'corrected',
+        type=Path,
+        help='Corrected 3\' ends TSV from RECTIFY'
+    )
+
+    validate_parser.add_argument(
+        '-o', '--output',
+        type=Path,
+        required=True,
+        help='Output validation results TSV'
+    )
+
+    # Ground truth sources (at least one required)
+    truth_group = validate_parser.add_argument_group(
+        'Ground truth sources (at least one required)'
+    )
+
+    truth_group.add_argument(
+        '--netseq-dir',
+        type=Path,
+        help='NET-seq BigWig directory (optional - requires pyBigWig)'
+    )
+
+    truth_group.add_argument(
+        '--netseq-samples',
+        nargs='+',
+        help='Specific NET-seq samples to use'
+    )
+
+    truth_group.add_argument(
+        '--annotation',
+        type=Path,
+        help='Gene annotation GTF/GFF with known 3\' ends'
+    )
+
+    truth_group.add_argument(
+        '--ground-truth',
+        type=Path,
+        help='TSV file with known true 3\' end positions'
+    )
+
+    # Validation parameters
+    param_group = validate_parser.add_argument_group('Validation parameters')
+
+    param_group.add_argument(
+        '--tolerance',
+        type=int,
+        default=1,
+        help='Position tolerance in bp for "correct" classification'
+    )
+
+    param_group.add_argument(
+        '--min-signal',
+        type=float,
+        default=0.5,
+        help='Minimum NET-seq signal for ground truth'
+    )
+
+    param_group.add_argument(
+        '--search-window',
+        type=int,
+        default=10,
+        help='Window size for finding nearest ground truth'
+    )
+
+    # Output options
+    validate_parser.add_argument(
+        '--verbose',
+        action='store_true',
+        help='Verbose logging'
+    )
+
+    return parser
+
+
+def main(argv: Optional[list] = None):
+    """Main entry point for RECTIFY CLI."""
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+
+    # Import commands only when needed
+    if args.command == 'correct':
+        from .core import correct_command
+        correct_command.run(args)
+    elif args.command == 'train-polya':
+        from .core import train_polya_command
+        train_polya_command.run(args)
+    elif args.command == 'validate':
+        from .core import validate_command
+        validate_command.run(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

rectify/config.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""
+Configuration constants for RECTIFY.
+
+This module centralizes:
+- Chromosome mappings (standard ↔ NCBI format)
+- Shift correction parameters (from NET-seq analysis)
+- Poly(A) tail model parameters
+- Indel detection parameters
+- NET-seq refinement parameters
+
+Author: Kevin R. Roy
+Date: 2026-03-09
+"""
+
+from typing import Dict
+
+# =============================================================================
+# Version
+# =============================================================================
+
+__version__ = "2.1.0"
+
+# =============================================================================
+# Chromosome Mappings
+# =============================================================================
+
+# Standard chromosome to NCBI genome format mapping (S. cerevisiae)
+CHROM_TO_GENOME: Dict[str, str] = {
+    'chrI': 'ref|NC_001133|',
+    'chrII': 'ref|NC_001134|',
+    'chrIII': 'ref|NC_001135|',
+    'chrIV': 'ref|NC_001136|',
+    'chrV': 'ref|NC_001137|',
+    'chrVI': 'ref|NC_001138|',
+    'chrVII': 'ref|NC_001139|',
+    'chrVIII': 'ref|NC_001140|',
+    'chrIX': 'ref|NC_001141|',
+    'chrX': 'ref|NC_001142|',
+    'chrXI': 'ref|NC_001143|',
+    'chrXII': 'ref|NC_001144|',
+    'chrXIII': 'ref|NC_001145|',
+    'chrXIV': 'ref|NC_001146|',
+    'chrXV': 'ref|NC_001147|',
+    'chrXVI': 'ref|NC_001148|',
+    'chrMito': 'ref|NC_001224|',
+}
+
+# Reverse mapping
+GENOME_TO_CHROM: Dict[str, str] = {v: k for k, v in CHROM_TO_GENOME.items()}
+
+# Chromosome sizes (sacCer3/R64)
+CHROM_SIZES: Dict[str, int] = {
+    'chrI': 230218,
+    'chrII': 813184,
+    'chrIII': 316620,
+    'chrIV': 1531933,
+    'chrV': 576874,
+    'chrVI': 270161,
+    'chrVII': 1090940,
+    'chrVIII': 562643,
+    'chrIX': 439888,
+    'chrX': 745751,
+    'chrXI': 666816,
+    'chrXII': 1078177,
+    'chrXIII': 924431,
+    'chrXIV': 784333,
+    'chrXV': 1091291,
+    'chrXVI': 948066,
+    'chrMito': 85779,
+}
+
+# =============================================================================
+# Shift Correction Parameters (from NET-seq Analysis)
+# =============================================================================
+
+# These represent how much the apparent position is shifted RIGHTWARD (downstream)
+# due to long poly(A) tails (>15 A's for nanopore) aligning to genomic A's/T's
+# To correct: shift LEFTWARD (upstream) by this amount
+SHIFT_CORRECTIONS_BY_ACOUNT: Dict[int, float] = {
+    0: 0.0,   # No downstream A's - no shift
+    1: 0.2,   # Minimal shift
+    2: 0.3,
+    3: 0.4,
+    4: 1.0,   # Moderate shift
+    5: 1.3,
+    6: 1.7,
+    7: 2.6,   # Strong shift
+    8: 2.8,
+    9: 2.9,
+    10: 3.8,  # Maximum observed shift (saturated)
+}
+
+# For A-counts > 10, use the 10A value (saturated)
+DEFAULT_MAX_SHIFT: float = 3.8
+
+# =============================================================================
+# Poly(A) Tail Model Parameters
+# =============================================================================
+
+# Minimum tail length for nanopore oligo-dT priming
+MIN_POLYA_LENGTH: int = 15
+
+# A-richness threshold for identifying poly(A) tails
+POLYA_RICHNESS_THRESHOLD: float = 0.8  # 80% A content
+
+# Window size for A-richness calculation
+POLYA_WINDOW_SIZE: int = 10
+
+# RTA adapter patterns to detect
+ADAPTER_POLY_T_MIN: int = 6          # Minimum poly(T) length
+ADAPTER_TC_MOTIFS = ['TC', 'TCTC', 'TCT']
+
+# Scoring thresholds for tail classification
+TAIL_SCORE_HIGH: float = 0.7    # Definite poly(A) tail
+TAIL_SCORE_LOW: float = 0.4     # Uncertain
+
+# =============================================================================
+# Indel Detection Parameters
+# =============================================================================
+
+# Maximum distance from 3' end to consider deletions as artifacts
+INDEL_SEARCH_WINDOW: int = 20  # bp
+
+# Maximum deletion size to consider as artifact
+INDEL_MAX_SIZE: int = 3  # bp
+
+# Minimum A-richness in flanking regions to classify as artifact
+INDEL_FLANK_A_THRESHOLD: float = 0.7  # 70% A content
+
+# Minimum flank length to check for A-richness
+INDEL_MIN_FLANK_LENGTH: int = 5  # bp
+
+# =============================================================================
+# Ambiguity Range Parameters
+# =============================================================================
+
+# Maximum shift to consider when calculating ambiguity ranges
+MAX_AMBIGUITY_SHIFT: int = 5  # bp
+
+# Window size for downstream A-count calculation
+DOWNSTREAM_WINDOW_SIZE: int = 10  # bp
+
+# =============================================================================
+# NET-seq Refinement Parameters
+# =============================================================================
+
+# Agreement threshold for combining WT and dst1 NET-seq data
+NETSEQ_AGREEMENT_THRESHOLD: float = 0.90  # 90% agreement at ±1bp
+
+# Window around CPA for peak detection
+NETSEQ_PEAK_WINDOW: int = 5  # ±5bp
+
+# Minimum signal threshold for peak calling (relative to max)
+NETSEQ_PEAK_THRESHOLD: float = 0.5  # 50% of max signal
+
+# Minimum peak signal for high confidence
+NETSEQ_SIGNAL_HIGH: float = 1.0
+NETSEQ_SIGNAL_MEDIUM: float = 0.5
+
+# Maximum distance between peaks to consider them "close"
+NETSEQ_PEAK_CLOSE_DISTANCE: int = 2  # bp
+
+# =============================================================================
+# AG Mispriming Parameters (from original RECTIFY)
+# =============================================================================
+
+# Window size for AG-richness calculation
+AG_RICHNESS_WINDOW: int = 50  # bp downstream
+
+# AG content threshold for flagging likely mispriming
+AG_RICHNESS_THRESHOLD: float = 0.65  # 65% A+G content
+
+# Minimum window size if near chromosome end
+AG_RICHNESS_MIN_WINDOW: int = 20  # bp
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+def get_shift_from_acount(a_count: int) -> float:
+    """
+    Get shift correction for given A-count.
+
+    Args:
+        a_count: Number of A's in downstream window
+
+    Returns:
+        Shift correction in bp (how much to shift leftward/upstream)
+    """
+    if a_count <= 10:
+        return SHIFT_CORRECTIONS_BY_ACOUNT.get(a_count, 0.0)
+    else:
+        return DEFAULT_MAX_SHIFT
+
+
+def validate_config():
+    """Validate configuration parameters."""
+    assert len(CHROM_TO_GENOME) == len(GENOME_TO_CHROM), "Chromosome mapping mismatch"
+    assert len(CHROM_TO_GENOME) == len(CHROM_SIZES), "Chromosome size mapping incomplete"
+    assert 0.0 <= POLYA_RICHNESS_THRESHOLD <= 1.0, "Invalid poly(A) richness threshold"
+    assert 0.0 <= AG_RICHNESS_THRESHOLD <= 1.0, "Invalid AG richness threshold"
+    assert MIN_POLYA_LENGTH > 0, "Invalid minimum poly(A) length"
+    assert INDEL_SEARCH_WINDOW > 0, "Invalid indel search window"
+
+
+# Run validation on import
+validate_config()

rectify/core/__init__.py

@@ -0,0 +1,32 @@
+"""
+RECTIFY core modules.
+
+This package contains the main correction algorithms:
+- bam_processor: BAM reading and 3' end extraction
+- atract_detector: A-tract ambiguity detection (universal)
+- ag_mispriming: AG-richness screening (oligo-dT methods)
+- polya_trimmer: Poly(A) tail modeling and trimming
+- indel_corrector: Indel artifact removal
+- netseq_refiner: NET-seq peak matching and refinement
+- spikein_filter: Spike-in RNA detection and filtering
+- output_writer: Unified output format
+
+And CLI command implementations:
+- correct_command: Main correction workflow
+- train_polya_command: Poly(A) model training
+- validate_command: Validation against NET-seq
+"""
+
+__all__ = [
+    "bam_processor",
+    "atract_detector",
+    "ag_mispriming",
+    "polya_trimmer",
+    "indel_corrector",
+    "netseq_refiner",
+    "spikein_filter",
+    "output_writer",
+    "correct_command",
+    "train_polya_command",
+    "validate_command",
+]