siRNAforge Logo

🚀 Getting Started

  • Installation
    • Recommended: pip/uv
    • Development Setup
    • Docker (Full Bioinformatics Stack)
    • Verify Installation
  • Getting Started & Quick Reference
    • 1. Install
    • 2. Run Your First Workflow
    • 3. Customize Inputs & References
    • 4. Inspect Results
    • 5. Understand the Scores
    • 6. Next Steps

📖 User Guide

  • CLI Reference
    • Help & Version
      • Main Help
      • Version
    • workflow
      • Help
        • Input Sources & Transcriptome References
    • search
      • Help
    • design
      • Help
      • Example: Design from Sample Data
        • Output Preview
    • validate
      • Help
      • Example: Validate Sample Data
    • config
    • sequences
      • Help
    • cache
      • Help
  • Usage Examples
    • Advanced Workflow Presets
      • Publication-Quality Screen
      • Custom FASTA + Transcriptome Override
    • Gene Search & Design Automations
      • Curated Transcript Panel
    • Batch Processing with QC Summaries
    • Design-Only with Chemical Modifications
    • miRNA-Biogenesis Mode
    • Nextflow Off-Target Pipeline Hand-Off
    • Docker-Friendly Pattern
    • See Also
  • Workflows
    • Complete Workflow
      • Output Structure
      • Common Options
    • Step-by-Step Workflow
    • Batch Processing
    • Variant Targeting (documented runs)
    • Docker Workflow
    • Nextflow Pipeline
  • Gene Search Functionality
    • TL;DR
    • Features
    • Quick Start
      • Command Line Usage
      • Python API Usage
        • Synchronous API
        • Asynchronous API
    • Supported Databases
      • Ensembl ✅ (Fully Implemented)
      • RefSeq 🚧 (Planned)
      • GENCODE 🚧 (Planned)
    • Data Models
    • Example Workflows
      • 1. Design siRNAs from Gene Search
      • 2. Compare Databases
    • Error Handling
    • Configuration
    • See Also
  • Scoring Overview
    • Quick Reference
    • Composite Score
    • Asymmetry Score
    • GC Content
    • Melting Temperature
    • Minimum Free Energy (MFE)
    • Filtering Recommendations
      • Standard (most applications)
      • Stringent (publication-quality)
      • Relaxed (difficult targets)
    • Output Columns
    • References
  • Thermodynamic Metrics Interpretation Guide
    • Quick Reference Table
    • Analyzing Your Results
      • Step 1: Load and Examine Data
      • Step 2: Identify High-Quality Candidates
      • Step 3: Troubleshoot Poor Performance
        • Low GC Content Issues
        • Poor Asymmetry Scores
        • Overly Stable Duplexes
    • Application-Specific Guidelines
      • For High-Efficiency Applications
      • For Broad Target Coverage
      • For Sensitive Cell Types
    • Experimental Validation Tips
      • Testing Multiple Candidates
      • Metric Correlation Analysis
      • Iterative Optimization
    • Common Troubleshooting
      • No High-Quality Candidates
      • All Candidates Have High Off-targets
      • System-Specific Optimization
    • Advanced Analysis
      • Composite Score Interpretation
      • Custom Scoring Functions
  • Tutorials
    • Python API Tutorial
      • Learning Objectives
      • Prerequisites
      • Getting Started
        • Import Core Components
        • Basic API Usage
      • Gene Search API
        • Synchronous Gene Search
        • Asynchronous Gene Search
      • Advanced API Usage
        • Custom Scoring
      • Configuration and Customization
        • Using Configuration Models
        • Environment-Based Configuration
      • Testing Your Code
        • Unit Testing API Usage
      • Best Practices
        • 1. Resource Management
        • 2. Progress Monitoring
        • 3. Memory-Efficient Processing
      • Next Steps
      • Key API Modules
    • Pipeline Integration Tutorial
      • When to Use the Pipeline
      • Prerequisites
      • Step 1 – Prepare Candidates
      • Step 2 – Configure References
      • Step 3 – Run Off-Target Analysis (embedded Nextflow)
      • Running Nextflow Directly (advanced)
        • Docker + local profile (no Docker-in-Docker)
      • Step 4 – Inspect Outputs
      • Troubleshooting
      • Additional Resources
    • Modular Override Guide
      • Design Philosophy
      • Default Behavior
        • Without Any Overrides
      • Surgical Overrides
        • Override miRNA Species Only
        • Override Transcriptome Reference
        • Add Custom Sequences to Defaults
        • Override BWA Indices Directly
      • Advanced Use Cases
        • Custom miRNA Database (Not Recommended)
        • Design-Only Mode
        • Genomic DNA Off-Target (Resource-Intensive)
      • Override Hierarchy
        • Example: Mixed Override
      • Cache Management
        • View Cache Status
        • Clear Stale Data
      • Common Workflows
        • 1. Human-Only Analysis (Fast)
        • 2. Multi-Species Comparative
        • 3. Custom Transcriptome + Standard miRNA
        • 4. Pre-Indexed Genomes (Production)
      • Troubleshooting
        • “No transcriptome data for species X”
        • “Species not recognized” or “Invalid species code”
        • “BWA index not found”
        • Custom FASTA not detected
      • Implementation Notes
        • Current Limitations
        • Future Enhancements
      • Species Normalization
        • Supported Input Formats
        • Why Normalization Matters
        • Registry Lookup
      • API Usage
      • Summary
    • Custom Scoring Tutorial
      • Understanding Thermodynamic Asymmetry Scoring
        • What is Thermodynamic Asymmetry?
        • The Science Behind Asymmetry Scoring
        • Research Foundation
        • Implementation in siRNAforge
        • Scoring Components
        • Comprehensive Thermodynamic Metrics in siRNAforge
        • Interpreting Asymmetry Scores
        • Integrated Scoring Guidelines
        • Context-Dependent Optimization
      • Custom Scoring Framework
        • Understanding the Scoring System
        • Implementing Custom Scorers
        • Integrating Machine Learning Models
      • Validation and Performance
        • Validating Custom Scores
        • Performance Optimization
      • Advanced Topics
        • Research Integration
        • Future Directions
    • Chemical Modification Patterns Reference
      • Overview
      • Built-In Modification Patterns
        • Standard 2’-O-Methyl (Recommended)
        • Minimal Terminal (Cost-Optimized)
        • Maximal Stability (Therapeutic-Grade)
      • FDA-Approved Example: Patisiran (Onpattro)
        • Guide Strand (Patisiran)
        • Passenger Strand (Patisiran)
        • Clinical Success
      • Modification Types Reference
        • 2’-O-Methyl (2OMe)
        • Phosphorothioate (PS)
        • 2’-Fluoro (2F)
        • Locked Nucleic Acid (LNA)
        • 2’-O-Methoxyethyl (MOE)
      • Custom Pattern Design
        • Design Principles
        • Pattern Template
        • Position Selection Strategies
      • Application-Specific Recommendations
        • In Vitro Screening (96-well, 384-well)
        • In Vitro Validation Studies
        • In Vivo Proof-of-Concept
        • Therapeutic Development
      • Synthesis and Ordering
        • Synthesis Vendors
        • Cost Estimates (2025)
        • Ordering Checklist
        • Timeline Expectations
      • Best Practices
        • 1. Design Before You Modify
        • 2. Test Incrementally
        • 3. Document Everything
        • 4. Match Pattern to Application
        • 5. Consider Delivery Method
        • 6. Archive Modification Files
      • Integration with siRNAforge
        • Command-Line Usage
        • Python API
        • Annotate Existing FASTA
      • Troubleshooting
        • Low Efficacy After Modification
        • High Cost Synthesis
        • Inconsistent Results
      • References
        • Key Publications
        • Regulatory Guidance
        • Patents
      • Contributing Patterns
    • Tutorial Overview

📚 Reference

  • Python API Usage
    • Basic Usage
    • Gene Search
      • Async Search
    • Complete Workflow
    • Chemical Modifications
    • File I/O
    • Error Handling
    • See Also
  • API Reference
    • Command Line Interface
      • patched_init()
      • filter_transcripts()
      • extract_canonical_transcripts()
      • search()
      • workflow()
      • offtarget()
      • design()
      • validate()
      • version()
      • config()
      • cache()
      • SequencesShowError
      • sequences_show()
      • sequences_annotate()
    • Core Modules
      • Design Engine
        • SiRNADesigner
        • MiRNADesigner
      • Thermodynamics Analysis
        • ThermodynamicCalculator
      • Off-Target Prediction
        • BwaAnalyzer
        • OffTargetAnalysisManager
        • create_temp_fasta()
        • validate_and_write_sequences()
        • build_bwa_index()
        • validate_sirna_sequences()
        • parse_fasta_file()
        • write_fasta_file()
        • check_tool_availability()
        • validate_index_files()
        • run_bwa_alignment_analysis()
        • aggregate_offtarget_results()
        • run_mirna_seed_analysis()
        • aggregate_mirna_results()
    • Data Models
      • SiRNA Models
        • FilterCriteria
        • OffTargetFilterCriteria
        • ScoringWeights
        • DesignMode
        • MiRNADesignConfig
        • DesignParameters
        • SequenceType
        • SiRNACandidate
        • DesignResult
      • Chemical Modifications
        • ConfirmationStatus
        • SourceType
        • Provenance
        • ChemicalModification
        • StrandRole
        • StrandMetadata
        • SequenceRecord
      • Off-Target Models
        • AlignmentStrand
        • AnalysisMode
        • MiRNADatabase
        • BaseAlignmentHit
        • OffTargetHit
        • MiRNAHit
        • BaseSummary
        • AnalysisSummary
        • MiRNASummary
        • BaseAggregatedSummary
        • AggregatedOffTargetSummary
        • AggregatedMiRNASummary
      • Transcript Annotation Models
        • Interval
        • TranscriptAnnotation
        • TranscriptAnnotationBundle
      • Validation Schemas
        • SchemaConfig
        • SiRNACandidateSchema
        • ORFValidationSchema
        • OffTargetHitsSchema
        • MiRNAAlignmentSchema
        • GenomeAlignmentSchema
    • Data Access
      • Base Data Classes
        • DatabaseError
        • DatabaseAccessError
        • GeneNotFoundError
        • DatabaseType
        • SequenceType
        • GeneInfo
        • TranscriptInfo
        • AbstractDatabaseClient
        • AbstractTranscriptAnnotationClient
        • EnsemblClient
        • RefSeqClient
        • GencodeClient
        • SequenceUtils
        • FastaUtils
        • get_database_display_name()
      • Gene Search
        • GeneSearchResult
        • GeneSearcher
        • search_gene_sync()
        • search_gene_with_fallback_sync()
        • search_multiple_databases_sync()
      • ORF Analysis
        • ORFInfo
        • SequenceAnalysis
        • ORFAnalyzer
        • create_orf_analyzer()
        • analyze_multiple_transcript_orfs()
      • Transcript Annotations
        • EnsemblTranscriptModelClient
        • VepConsequenceClient
      • miRNA Management
        • MiRNASource
        • MiRNADatabaseManager
        • main()
      • Species Registry
        • normalize_species_name()
    • Pipeline Integration
      • Nextflow CLI
        • build_bwa_index_cli()
        • aggregate_results_cli()
        • aggregate_mirna_results_cli()
      • Nextflow Configuration
        • EnvironmentInfo
        • NextflowConfig
      • Nextflow Runner
        • NextflowRunner
        • NextflowExecutionError
    • Workflow Orchestration
      • WorkflowConfig
        • WorkflowConfig.__init__()
      • SiRNAWorkflow
        • SiRNAWorkflow.__init__()
        • SiRNAWorkflow.run_complete_workflow()
        • SiRNAWorkflow.step1_retrieve_transcripts()
        • SiRNAWorkflow.resolve_variants_step()
        • SiRNAWorkflow.step2_validate_orfs()
        • SiRNAWorkflow.step3_design_sirnas()
        • SiRNAWorkflow.step4_generate_reports()
        • SiRNAWorkflow.step5_offtarget_analysis()
      • run_sirna_workflow()
      • run_offtarget_only_workflow()
    • Validation
      • Validation Configuration
        • ValidationLevel
        • ValidationStage
        • ValidationConfig
        • ValidationPresets
      • Validation Middleware
        • ValidationReport
        • ValidationMiddleware
      • Validation Utilities
        • ValidationResult
        • ValidationUtils
    • Utilities
      • Logging Utilities
        • configure_logging()
        • get_logger()
      • Modification Patterns
        • apply_standard_2ome_pattern()
        • apply_minimal_terminal_pattern()
        • apply_maximal_stability_pattern()
        • get_modification_pattern()
        • apply_modifications_to_candidate()
        • get_modification_summary()
      • Resource Resolver
        • InputSource
        • resolve_input_source()
    • Chemical Modifications
      • parse_chem_mods()
      • parse_provenance()
      • parse_header()
      • load_metadata()
      • merge_metadata_into_fasta()
      • save_metadata_json()
  • Data Models, Filtering & Scoring: Technical Reference
    • Overview
    • 1. Core Data Models
      • 1.1 SiRNACandidate
        • Sequence Validation
      • 1.2 DesignParameters
      • 1.3 FilterCriteria
      • 1.4 OffTargetFilterCriteria
      • 1.5 ScoringWeights
    • 2. Scoring Algorithms
      • 2.1 Composite Score Calculation
      • 2.2 Thermodynamic Asymmetry Score
      • 2.3 GC Content Score
      • 2.4 Duplex Stability Score
      • 2.5 Target Accessibility Score
      • 2.6 Off-Target Score
      • 2.7 Empirical Score (Reynolds Rules)
    • 3. Filter Implementation
      • 3.1 Early Filtering (Enumeration Stage)
      • 3.2 Quality Filters (Scoring Stage)
      • 3.3 Filter Status Codes
    • 4. Threshold Justification
      • 4.1 GC Content: 35-60%
      • 4.2 Asymmetry Score: ≥0.65
      • 4.3 Poly-runs: ≤3 consecutive
      • 4.4 MFE: -2 to -8 kcal/mol
      • 4.5 Melting Temperature: 60-78°C
    • 5. miRNA-Biogenesis Mode
      • 5.1 MiRNADesignConfig
      • 5.2 miRNA-Specific Scoring
    • 6. Off-Target Analysis Models
      • 6.1 OffTargetHit
      • 6.2 MiRNAHit
      • 6.3 Supported miRNA Databases
    • 7. Chemical Modification Models
      • 7.1 StrandMetadata
      • 7.2 ChemicalModification
      • 7.3 Supported Modification Patterns
    • 8. Workflows Requiring Documentation
      • 8.1 Nextflow Pipeline
      • 8.2 ORF Validation
      • 8.3 Transcript Retrieval
    • 9. References
    • Appendix A: Default Parameter Summary
    • Appendix B: Scoring Weight Defaults
  • Chemical Modification Annotation Specification
    • Overview
    • Data Models
      • ChemicalModification
      • Provenance
      • StrandMetadata
      • SequenceRecord
    • FASTA Header Encoding
    • JSON Sidecar Format
    • Python API
      • Loading Metadata
      • Parsing FASTA Headers
      • Merging Metadata into FASTA
      • Creating Metadata Programmatically
    • CLI Usage
      • Show Sequences with Metadata
      • Annotate FASTA with Metadata
    • Integration with SiRNACandidate
    • Modification Type Reference
    • Position Numbering
    • Backward Compatibility
    • Best Practices
    • Example Workflow
    • Future Extensions
    • References
  • Changelog
    • Unreleased
    • [0.3.4] - 2025-12-31
      • Added
      • Improvements
      • Documentation
    • [0.3.3] - 2025-12-15
      • Bug Fixes
    • [0.3.1] - 2025-12-04
      • Added
      • Improvements
      • Bug Fixes
      • Documentation
    • [0.3.0] - 2025-11-21
      • Improvements
      • Bug Fixes
      • Testing
      • Build & Infrastructure
    • 0.2.2 - 2025-10-26
      • New Features
      • Improvements
      • Bug Fixes
      • Documentation
      • Testing
      • Dependencies
    • 0.2.1 - 2025-10-24
      • New Features
      • Improvements
      • Bug Fixes
      • Documentation
      • Testing
      • Dependencies
      • Performance
    • 0.2.0 - 2025-09-27
      • New Features
      • Improvements
      • � Bug Fixes
      • 📊 Performance
      • Testing & Infrastructure
      • Documentation
      • Dependencies & Architecture
    • 0.1.0 - 2025-09-06
      • Added
      • Core Features
      • Supported Operations
      • Technical Stack
  • Glossary

🔧 Developer

  • Developer Documentation
    • siRNAforge Architecture
      • Short version (TL;DR)
      • Overview
      • System Architecture Flow
      • Package Structure
        • Directory Structure
      • Architectural Layers
        • 1. CLI Layer (cli.py)
        • Configuration & Default Resolution (sirnaforge.config)
        • 2. Workflow Layer (workflow.py)
        • 3. Core Layer (core/)
        • 4. Model Layer (models/)
        • 5. Data Layer (data/)
        • 6. Validation Layer (validation/)
        • 7. Pipeline Layer (pipeline/)
      • Design Principles
        • 1. Type Safety
        • 2. Separation of Concerns
        • 3. Dependency Injection
        • 4. Error Handling
        • 5. Configuration Management
      • Data Flow
        • 1. Complete Workflow
        • 2. Component Interaction
      • Extension Points
        • 1. Custom Scoring Functions
        • 2. Additional Data Sources
        • 3. New Validation Rules
      • Performance Considerations
        • 1. Asynchronous Operations
        • 2. Memory Management
        • 3. Caching
      • Testing Architecture
        • 1. Unit Tests (tests/unit/)
        • 2. Integration Tests (tests/integration/)
        • 3. Pipeline Tests (tests/pipeline/)
      • Deployment Architecture
        • 1. Local Development
        • 2. Container Deployment
        • 3. Pipeline Deployment
      • Future Architecture Considerations
        • 1. Microservices
        • 2. Cloud Integration
        • 3. Plugin System
    • Development Guide
      • Development Environment Setup
        • Prerequisites
        • Quick Start
        • Manual Setup
      • Make Commands Reference
        • Testing Commands
        • Variant mode validation & reporting (new)
        • Code Quality Commands
        • Docker Commands
        • Documentation Commands
        • Utility Commands
      • Development Workflow
      • Branching & Release Strategy
        • How to Work Day-to-Day
        • Hygiene Rules (Recommended)
        • Version & Tag Hygiene
        • Recommended GitHub Branch Protection
        • Versioning Guidance (PEP 440)
        • Docker Image Tags (Recommended)
        • Typical Development Cycle
        • Working with Tests
        • Docker Development
      • Code Style and Standards
        • Python Code Style
        • Code Organization Principles
      • Testing Best Practices
        • 1. Test Organization
        • 2. Test Fixtures
        • 3. Parametrized Tests
        • 4. Mock External Dependencies
      • Contribution Guidelines
        • 1. Pull Request Process
        • 2. Commit Message Format
        • 3. Pull Request Guidelines
        • 4. Code Review Process
      • Advanced Development
        • 1. Adding New Algorithms
        • 2. Adding New Data Sources
        • 3. Performance Profiling
      • Debugging
        • 1. Logging
        • 2. Interactive Debugging
        • 3. Testing with Real Data
      • Release Process
        • 1. Version Management
        • 2. Building and Distribution
        • 3. Documentation Deployment
      • Getting Help
    • Testing Guide
      • Quick Commands
        • Development (Python-only)
        • Docker (Full environment)
        • Test Categories by Tier
      • Local Development Testing
        • 1. Initial Setup (Required - Run Once)
        • 2. Fast Iteration Cycle
        • 3. Code Quality Checks
        • 4. Pre-Commit Validation
      • Docker Testing (Comprehensive Validation)
        • Prerequisites
        • 1. Build Docker Image
        • 2. Run Tests in Container
        • 3. Manual Docker Verification
      • Best Practices
        • Development Workflow
        • Resource Management
        • Timeouts and Expectations
      • Quick Health Checks
    • Comprehensive Review: Chemical Modification Handling in siRNAforge
      • Executive Summary
        • Key Strengths
        • Current Gaps
      • Current Infrastructure
        • 1. Data Models (src/sirnaforge/models/modifications.py)
        • 2. Utility Functions (src/sirnaforge/modifications.py)
        • 3. Integration Points in SiRNACandidate
        • 4. FASTA Header Encoding Format
        • 5. JSON Sidecar Format
      • Integration Opportunities
        • A. Workflow Output Integration
        • B. Annotation as Optional Output
        • C. Separate Annotation Command
      • Recommended Integration Strategy
        • Phase 1: Documentation and Examples (Immediate)
        • Phase 2: Workflow Integration (Short-term)
        • Phase 3: Advanced Features (Long-term)
      • Implementation Patterns
        • Pattern 1: Keep as Annotations (Recommended)
        • Pattern 2: Integrated Scoring (Advanced)
        • Pattern 3: Hybrid Approach (Flexible)
      • Modification Pattern Library
        • Standard Patterns (Examples)
      • Testing Strategy
        • Test Categories
        • New Test Coverage Needed
      • Recommendations Summary
        • 1. Immediate Actions (Low Effort, High Impact)
        • 2. Short-term Enhancements (Moderate Effort)
        • 3. Long-term Vision (High Effort, High Value)
      • Conclusion
      • Appendix: Common Modification Types
    • Quick Links
  • Chemical Modification Integration Guide for Developers
    • Quick Start
      • 1. Basic Workflow
      • 2. Load Existing Patterns
      • 3. Annotate FASTA Files
    • Integration Patterns
      • Pattern A: Post-Processing (Recommended for Most Cases)
      • Pattern B: Inline Integration
      • Pattern C: Hybrid (Best for Flexibility)
    • Best Practices
      • 1. Validation
      • 2. Pattern Library Organization
      • 3. Provenance Tracking
      • 4. Version Control
      • 5. Testing
    • Common Use Cases
      • Use Case 1: Batch Annotation
      • Use Case 2: Synthesis Planning
      • Use Case 3: Cost Estimation
    • Troubleshooting
      • Issue: Metadata not appearing in FASTA headers
      • Issue: Validation errors for positions
      • Issue: Pattern not found
    • Advanced Topics
      • Custom Modification Types
      • Multi-Strand Complexes
      • Integration with Workflow Outputs
    • References
siRNAforge
  • Search

© Copyright 2025, Austin S. Hovland.