Spymot is a comprehensive protein analysis platform that combines motif detection with 3D structure validation using AlphaFold2 confidence scores. Designed for cancer biology research, drug discovery, and functional genomics, Spymot provides deep insights into protein function through systematic analysis of short linear motifs (SLiMs) and targeting signals.

Spymot is now available on PyPI and can be installed worldwide!

pip install spymot

• PyPI (Main): https://pypi.org/project/spymot/ - LIVE! ✅
• Test PyPI: https://test.pypi.org/project/spymot/ - LIVE! ✅
• Version: 2.1.2.dev2 published successfully
• Installable globally: pip install spymot

Anyone can now install your package with:

pip install spymot

Spymot is available as a Python package that provides unified access to both V1 and V2 functionality through a single, easy-to-use interface.

• 94.6% coverage of critical protein motifs (316+ patterns)
• AlphaFold2 integration with pLDDT confidence scoring
• Cancer-focused analysis with relevance scoring
• Context-aware detection (topology, disorder, cellular localization)
• Multiple interfaces: CLI, Python API, Interactive mode
• Rich output formats: JSON, YAML, TXT with biological interpretation

• Tumor suppressor analysis (p53, BRCA1 degradation signals)
• Kinase characterization (CDK, ATM/ATR phosphorylation sites)
• Therapeutic target assessment (allosteric pockets, drug binding)
• Biomarker discovery (cancer-specific PTM signatures)
• Drug resistance analysis (EGFR T790M, conformational changes)

Moves beyond sequence-based detection to incorporate 3D structural context, enabling identification of discontinuous motifs and providing mechanistic insights into protein function and dysfunction.

Perfect for researchers in structural biology, cancer research, drug discovery, and bioinformatics.

This repository contains two main versions of Spymot:

• Core motif detection functionality
• Basic AlphaFold integration
• Simple CLI interface
• Essential motif database

• 94.6% motif coverage (316+ patterns)
• Advanced context-aware detection
• Comprehensive cancer relevance scoring
• Rich JSON output with biological interpretation
• Production-ready features and extensive testing

The unified Python package provides access to both versions through a single interface:

src/spymot/                    # Main package
├── __init__.py               # Package initialization
├── _version.py               # Version management
├── cli.py                    # Unified CLI interface
├── v1/                       # V1 functionality
│   ├── __init__.py
│   └── cli.py
└── v2/                       # V2 functionality
    ├── __init__.py
    └── scripts/
        ├── __init__.py
        ├── enhanced_cli.py
        ├── interactive_cli.py
        └── enhanced_demo.py

Package Features:

• Unified Interface: Single spymot command with version selection
• Pip Installable: pip install spymot for easy installation
• Version Management: Automatic versioning with setuptools_scm
• Development Tools: Black, Ruff, MyPy, and Pytest configuration
• MIT License: Open source and freely available

Spymot represents a major leap in bioinformatics by moving beyond traditional sequence-based detection to incorporate highly accurate, predicted three-dimensional context using AlphaFold2.

# Install from PyPI (when published)
pip install spymot

# Or install from source for development
git clone https://github.com/erfanzohrabi/spymot.git
cd spymot
pip install -e .

# Clone the repository
git clone https://github.com/erfanzohrabi/spymot.git
cd spymot

# Choose your version:
# For production use (recommended):
cd V2
pip install -r requirements.txt
pip install -e .

# For basic functionality:
cd V1
pip install -r requirements.txt

# Unified interface
spymot --help
spymot info

# V1 functionality
spymot v1 analyze protein.fasta --format json
spymot v1 pdb 1TUP --format json

# V2 functionality  
spymot v2 analyze protein.fasta --database all --cancer-only
spymot v2 databases --verbose

# Interactive mode
spymot interactive --version v2

# V1 functionality
from spymot import analyze_sequence, scan_motifs
result = analyze_sequence("p53", "MEEPQSDPSVEPPLSQETFSD...")

# V2 functionality
from spymot import EnhancedSpymotAnalyzer
analyzer = EnhancedSpymotAnalyzer()
result = analyzer.analyze_sequence_comprehensive("p53", "MEEPQSDPSVEPPLSQETFSD...")

# Package info
from spymot import get_version_info
info = get_version_info()
print(f"Version: {info['version']}")

# Analyze a protein sequence
python -m spymot_enhanced.cli analyze protein.fasta --database all --format json

# Cancer-focused analysis
python -m spymot_enhanced.cli analyze oncogene.fasta --database cancer --cancer-only

# Interactive mode
python -m spymot_enhanced.cli interactive

from spymot_enhanced import EnhancedSpymotAnalyzer

# Initialize analyzer
analyzer = EnhancedSpymotAnalyzer()

# Analyze sequence
result = analyzer.analyze_sequence_comprehensive(
    sequence="MEEPQSDPSVEPPLSQETFSD...",
    protein_id="p53_tumor_suppressor",
    min_confidence=0.4
)

print(f"Total motifs: {result['summary']['total_motifs_detected']}")
print(f"Cancer relevance: {result['interpretation']['cancer_relevance_assessment']}")

from spymot.analyzer import analyze_sequence

# Analyze a protein sequence
result = analyze_sequence(
    name="my_protein",
    seq="MEEPQSDPSVEPPLSQETFSD..."
)

print(f"Found {result['analysis_summary']['total_motifs']} motifs")

• APC/C Degrons: D-box (R-x-x-L), KEN box, ABBA motif
• SCF Degrons: βTrCP phosphodegron, Cdc4 phosphodegron
• Specialized Degrons: HIF-α ODD, PIP-box, p27 degron

• Cell Cycle: CDK consensus (S/T-P), PLK1 sites
• DNA Damage: ATM/ATR (S/T-Q), Chk1/Chk2 sites
• Survival: AKT (R-x-R-x-x-S/T), PKA consensus
• Stress Response: p38/JNK sites, CK2 sites

• SH2 Domains: General (pY-x-x), Grb2, STAT3, Src
• SH3 Domains: Class I (P-x-x-P-x-R), Class II (x-P-x-x-P-x)
• PDZ Domains: Class I (S/T-x-V/I), Class II (Φ-x-Φ)
• 14-3-3 Binding: Mode 1 (R-S-x-x-S-x-P), Mode 2 (R-x-x-S/T-x-x-x-P)

• Nuclear Localization: Classical NLS, Bipartite NLS, PY-NLS
• Nuclear Export: CRM1-dependent NES variants
• Nuclear Retention: DNA-binding motifs, chromatin association

• Mitochondrial: Matrix targeting sequence, intermembrane space
• ER Targeting: Signal peptide, KDEL retention, KKXX retrieval
• Peroxisomal: PTS1 (S-K-L variants), PTS2 consensus
• Chloroplast: Transit peptide consensus

✅ 88 motifs detected (5 cancer-relevant, 37 high-confidence)
✅ Post-translational modifications: 42 motifs
✅ Nuclear transport signals: Import/Export sequences identified
✅ Protein-protein interactions: 9 binding motifs detected
✅ Cellular targeting: 22 trafficking signals found
✅ Quality coverage: 82.4% with confidence scoring

{
  "metadata": {
    "spymot_version": "2.0.0",
    "analysis_timestamp": "2025-01-27T10:30:00",
    "database_sources": ["hardcoded", "ELM", "PROSITE", "Literature"]
  },
  "protein_info": {
    "id": "p53_tumor_suppressor",
    "length": 393,
    "uniprot": "P04637",
    "molecular_weight": 43653.24,
    "isoelectric_point": 6.33
  },
  "motifs": [
    {
      "name": "DEG_APC_Dbox",
      "start": 249,
      "end": 252,
      "match": "RPIL",
      "pattern": "R..L",
      "type": "Degron",
      "description": "APC/C destruction box",
      "cancer_relevance": "very_high",
      "confidence_score": 0.95,
      "functional_category": "protein_degradation",
      "biological_process": "cell_cycle",
      "clinical_significance": "high_therapeutic_target",
      "has_3d_support": true,
      "plddt_mean": 85.2,
      "confidence_level": "confident"
    }
  ],
  "quality_metrics": {
    "total_coverage": 0.847,
    "high_confidence_motifs": 23,
    "cancer_relevant_count": 15
  }
}

# Analyze protein sequence
python -m spymot_enhanced.cli analyze INPUT_FILE [OPTIONS]

# Interactive mode
python -m spymot_enhanced.cli interactive

# Show database information
python -m spymot_enhanced.cli databases --verbose

# Analyze protein sequence
python -m spymot.cli analyze protein.fasta --format json

# Show available databases
python -m spymot.cli databases

# PDB structure lookup
python -m spymot.cli pdb 1TUP --format json

# V2 Enhanced tests
cd V2
python test_enhanced_system.py
# Expected: "6/6 tests passed, ALL TESTS PASSED!"

# V1 Basic tests
cd V1
python test_system.py

• Database Loading: Verify all 316 motifs load correctly
• Motif Scanning: Test different database combinations
• Context Validation: Check N-terminal/C-terminal specificity
• Quality Scoring: Validate confidence and cancer relevance scores
• Structure Integration: Test AlphaFold2 pLDDT integration
• Output Formats: Verify JSON/YAML/TXT consistency

# Analyze p53 mutations in cancer patients
p53_variants = ["WT", "R273H", "R175H", "G245S"]
for variant in p53_variants:
    results = analyze_sequence(f"p53_{variant}", get_sequence(variant))
    print(f"{variant}: {results['quality_metrics']['cancer_relevant_count']} functional motifs")

# Screen protein family for druggable motifs
for protein in protein_family/*.fasta; do
    python -m spymot_enhanced.cli analyze $protein --database all --format json > ${protein%.fasta}_analysis.json
done

# Compare motif profiles between normal and disease states
def find_biomarker_motifs(normal_proteins, cancer_proteins):
    normal_motifs = {}
    cancer_motifs = {}
    
    for protein in normal_proteins:
        results = analyze_sequence(f"normal_{protein}", get_sequence(protein))
        normal_motifs[protein] = results['motifs']
    
    for protein in cancer_proteins:
        results = analyze_sequence(f"cancer_{protein}", get_sequence(protein))
        cancer_motifs[protein] = results['motifs']
    
    return compare_motif_profiles(normal_motifs, cancer_motifs)

import multiprocessing as mp
from spymot_enhanced import EnhancedSpymotAnalyzer

def analyze_batch(protein_list, n_processes=4):
    analyzer = EnhancedSpymotAnalyzer()
    
    def worker(protein_data):
        name, sequence = protein_data
        return analyzer.analyze_sequence_comprehensive(name, sequence)
    
    with mp.Pool(n_processes) as pool:
        results = pool.map(worker, protein_list)
    
    return results

# Process 1000+ proteins efficiently
large_dataset = load_protein_dataset("proteome.fasta")
batch_results = analyze_batch(large_dataset, n_processes=8)

• V2/docs/ENHANCED_SPYMOT_DOCUMENTATION.md: Comprehensive guide (40+ pages)
• V2/docs/MOTIFS_KNOWLEDGE.md: Biological knowledge base (500+ lines)
• V2/docs/CLI_USAGE_GUIDE.md: Command-line interface guide
• IMPORTANCE.md: Scientific foundation and mechanistic imperative

• ELM Database: Eukaryotic Linear Motif resource - canonical SLiM classes
• PROSITE: Documented functional sites and targeting signals
• Literature Curation: Cancer biology reviews and trafficking signal studies

Spymot uses the AlphaFold Protein Structure Database to assess 3D structural context:

• pLDDT Scores: Per-residue confidence from AlphaFold models
• Threshold: ≥70 pLDDT indicates reliable 3D structure
• Coverage: 200M+ protein structures from model organisms

Spymot uses AlphaFold2 pLDDT scores to validate motif predictions:

• pLDDT > 90: Very high confidence - motif likely structured and functional
• pLDDT 70-90: Confident - motif probably functional with good structure
• pLDDT 50-70: Low confidence - motif may be disordered but still functional
• pLDDT < 50: Very low confidence - motif prediction uncertain

Short Linear Motifs are 3-10 amino acid sequences that mediate crucial protein functions:

1. Degrons: Target proteins for degradation (APC/C, SCF complexes)
2. Kinase Sites: Phosphorylation targets (CDK, ATM/ATR, PKA)
3. Interaction Motifs: Protein binding sites (SH2, SH3, PDZ, 14-3-3)
4. Localization Signals: Subcellular targeting (NLS, NES, organellar signals)

• Tumor Suppressors: p53 contains 15+ regulatory motifs
• Oncoproteins: Myc, β-catenin rely on motifs for function/regulation
• Drug Targets: Kinase sites are primary targets for cancer therapy
• Biomarkers: Motif mutations predict treatment response

V2/
├── src/spymot_enhanced/          # Main package
│   ├── enhanced_analyzer.py      # Core analysis engine
│   ├── context_aware_detector.py # Smart detection system
│   ├── enhanced_motifs_db.py     # 316+ motif patterns
│   ├── external_tools.py         # Structural predictions
│   └── legacy/                   # Original Spymot compatibility
├── scripts/                      # Command-line interfaces
│   ├── enhanced_cli.py              # Main CLI
│   ├── enhanced_demo.py             # Interactive demo
│   └── interactive_cli.py           # Interactive mode
├── tests/                        # Comprehensive test suite
├── examples/                     # Usage examples and sample data
├── data/                         # Motif databases (CSV files)
└── docs/                         # Complete documentation

V1/
├── spymot/                       # Core modules
│   ├── analyzer.py               # Core analysis engine
│   ├── motifs.py                 # Motif detection
│   ├── afdb.py                   # AlphaFold integration
│   ├── targeting.py              # Signal prediction
│   ├── cli.py                    # Command-line interface
│   └── utils.py                  # Utilities
├── tests/                        # Test suite
├── data/                         # Motif databases
└── examples/                     # Usage examples

• Regex-Based Scanning: Fast motif detection using compiled patterns
• API Rate Limiting: Respectful AlphaFold DB queries with timeout handling
• Batch Optimization: Efficient parallel processing for multiple sequences

# V2 Enhanced analysis
python -m spymot_enhanced.cli analyze egfr.fasta --id P00533 --verbose
# Detects: signal peptide, kinase domain motifs, internalization signals

# V1 Basic analysis
python -m spymot.cli analyze egfr.fasta --id P00533 --format json

# V2 Enhanced analysis
python -m spymot_enhanced.cli analyze brca1.fasta --id P38398 --cancer-only
# Identifies: RING domain, nuclear localization, phosphorylation sites

# V1 Basic analysis
python -m spymot.cli analyze brca1.fasta --id P38398 --format txt

# V2 Enhanced analysis
python -m spymot_enhanced.cli analyze cmyc.fasta --id P01106 --format txt
# Shows: bHLH domain, nuclear signals, degradation motifs

# V1 Basic analysis
python -m spymot.cli analyze cmyc.fasta --id P01106 --format json

# Fork and clone the repository
git clone https://github.com/erfanzohrabi/spymot.git
cd spymot

# Choose version for development
cd V2  # or V1

# Create development environment
python -m venv spymot-dev
source spymot-dev/bin/activate

# Install development dependencies
pip install -r requirements.txt
pip install -e .

# Run tests
python test_enhanced_system.py  # V2
# or
python test_system.py  # V1

# V2 Enhanced tests
cd V2
python -m pytest tests/ -v
python test_enhanced_system.py

# V1 Basic tests
cd V1
python -m pytest tests/ -v
python test_system.py

Add new motifs to the database by creating entries in the CSV files or updating the hardcoded motif lists. Each new motif should include:

• Pattern: Regular expression or consensus sequence
• Biological Function: Clear description of the motif's role
• Cancer Relevance: Assessment of oncological significance
• Literature Support: Reference to experimental validation
• Context Requirements: Position constraints (N-terminal, C-terminal, etc.)

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow Python PEP 8 style guidelines
• Add tests for new functionality
• Update documentation for new features
• Ensure backward compatibility when possible

• Documentation: Check the comprehensive guides in V2/docs/ and documentation/
• Examples: See V2/examples/ and examples_and_demos/ for usage examples
• Issues: Report bugs on GitHub Issues

If you use Spymot in your research, please cite the relevant database sources:

• ELM Database: Kumar et al. (2022) Nucleic Acids Research
• PROSITE: Sigrist et al. (2021) Nucleic Acids Research
• AlphaFold2: Jumper et al. (2021) Nature

This project is licensed under the MIT License - see the LICENSE file for details.

• ELM Consortium for the comprehensive linear motif database
• SIB Swiss Institute of Bioinformatics for PROSITE patterns
• DeepMind for AlphaFold2 structure predictions
• Cancer research community for functional validation of motifs
• Scientific community for advancing protein structure prediction

• SignalP: Professional signal peptide prediction
• ELM Database: Eukaryotic Linear Motif resource
• Pfam: Protein family database
• COSMIC: Cancer mutation database
• AlphaFold Database: 3D structure predictions

• Total Motifs: 316+ curated patterns
• Cancer-Relevant: 200+ oncological motifs
• Signal Peptides: 100+ targeting sequences
• Test Coverage: 94.6% of must-detect motifs
• Documentation: 40+ pages of comprehensive guides
• Examples: Multiple usage scenarios and output formats

• Oncogene Analysis: Detect degrons, phosphodegrons, and regulatory motifs in tumor suppressors
• Drug Target Identification: Find druggable motifs and interaction sites
• Biomarker Discovery: Identify cancer-relevant motifs in protein panels
• Pathway Analysis: Map signaling motifs across cancer-related pathways

• Secretory Pathway: Signal peptides, ER retention, Golgi targeting
• Organellar Import: Mitochondrial, peroxisomal, nuclear targeting signals
• Membrane Trafficking: Endocytic motifs, vesicle transport signals
• Subcellular Localization: Predict protein distribution and trafficking routes

• AlphaFold Validation: Assess 3D structure confidence for motif regions
• Domain Organization: Identify functional domains and interaction motifs
• Structure-Function: Correlate motif locations with structural features
• Experimental Design: Guide mutagenesis and functional studies

• Machine Learning Integration: AI-powered motif prediction
• Multi-species Analysis: Cross-species motif conservation
• Web Interface: Browser-based analysis platform
• API Development: RESTful API for integration
• Cloud Deployment: Scalable cloud-based analysis

• Dynamic Motif Analysis: Time-resolved motif detection
• Network Analysis: Protein interaction network integration
• Drug Design: Structure-based drug discovery tools
• Personalized Medicine: Patient-specific motif analysis

🧬 Spymot: Empowering protein functional analysis through comprehensive motif detection and structure validation.

Developed by Erfan Zohrabi for cancer biology research and protein functional analysis.

# Install build tools
pip install build twine

# Build package
python -m build

# Check package
twine check dist/*

# Upload to PyPI
twine upload dist/*

# Install from PyPI
pip install spymot

• Name: spymot
• Version: 2.0.0
• Description: Advanced Protein Motif Detection with AlphaFold Structural Validation
• Author: Erfan Zohrabi
• License: MIT
• Python: >=3.8
• Dependencies: numpy, requests, click, PyYAML

# Python Package (Recommended)
pip install spymot

# Development Installation
git clone https://github.com/erfanzohrabi/spymot.git
cd spymot
pip install -e .

# Legacy V2 (Manual)
cd spymot/V2
pip install -r requirements.txt
pip install -e .

# Legacy V1 (Manual)
cd spymot/V1
pip install -r requirements.txt

# Python Package (Recommended)
spymot --help
spymot v1 analyze protein.fasta --format json
spymot v2 analyze protein.fasta --database all --cancer-only
spymot interactive --version v2

# Legacy V2 Enhanced
python -m spymot_enhanced.cli analyze protein.fasta --database all --format json
python -m spymot_enhanced.cli interactive

# Legacy V1 Basic
python -m spymot.cli analyze protein.fasta --format json
python -m spymot.cli pdb 1TUP --format json

# V2 Tests
cd V2 && python test_enhanced_system.py

# V1 Tests
cd V1 && python test_system.py

For detailed documentation, examples, and advanced usage, see the respective README files in V1/ and V2/ directories.

Spymot is now available as a Python package! This major update provides:

✅ Unified Installation: pip install spymot
✅ Single Command Interface: spymot v1 and spymot v2
✅ Easy Integration: Import directly in Python scripts
✅ Version Management: Automatic versioning and updates
✅ Development Tools: Complete development environment setup
✅ PyPI Ready: Ready for distribution on Python Package Index

Upgrade your workflow:

# Old way (manual)
cd V2 && python -m spymot_enhanced.cli analyze protein.fasta

# New way (package)
pip install spymot
spymot v2 analyze protein.fasta --database all --cancer-only

The Python package maintains full backward compatibility while providing a much cleaner and more professional user experience!