k-sites 1.1.0

Universal K-Sites: AI-Powered CRISPR Guide RNA Design Platform with Pathway-Aware Off-Target Filtering

K-Sites: Advanced CRISPR Guide RNA Design Platform

K-Sites is a comprehensive CRISPR guide RNA design platform that integrates GO term analysis with KEGG pathway graph analytics to identify non-pleiotropic gene targets and design optimal gRNAs with pathway-aware off-target filtering.

🌟 Features

Non-Pleiotropic Gene Identification

• Multi-database integration: Queries GO.org, UniProt, and KEGG simultaneously
• Pleiotropy scoring algorithm: Exponential decay scoring based on number of associated Biological Process GO terms
• Evidence-based filtering: Distinguishes experimental evidence (IDA, IMP, IGI) from computational predictions (IEA)
• Cross-species validation: Verifies gene specificity across model organisms (human, mouse, fly, worm)
• Customizable thresholds: User controls acceptable pleiotropy level (0-10 scale)
• Weighted ranking: Combines specificity, evidence quality, literature support, and conservation scores

RAG-Based Phenotype Prediction

• Real-time PubMed integration: NCBI Entrez API queries
• Targeted searches: Gene knockout/deletion studies, mutant phenotype reports, viability assessments, CRISPR guide literature
• Smart query construction: Multiple query strategies per gene
• Abstract and full-text retrieval: PMC Open Access integration
• Batch processing: Efficient multi-gene analysis
• Semantic embeddings: SentenceTransformer (all-MiniLM-L6-v2)
• Vector search: FAISS L2 distance indexing
• Adaptive retrieval: Relevance threshold filtering, diversity weighting
• Phenotype extraction & classification: NLP pattern matching with severity categorization (LETHAL, SEVERE, MODERATE, MILD, UNKNOWN)
• Risk assessment: CRITICAL/HIGH/MEDIUM/LOW/UNKNOWN classification

Integrated Workflow

• End-to-end pipeline: From gene selection to experimental recommendation
• Pathway-aware off-target filtering: Prevents disruption of critical pathways
• Publication-ready HTML reports: Comprehensive analysis with recommendations
• Multiple output formats: CSV, FASTA, and HTML reports

🛠️ Installation

Prerequisites

• Python 3.8+
• Git
• Docker (for Neo4j graph database, optional)

Setup

1. Clone the repository:

git clone https://github.com/yourusername/k-sites.git
cd k-sites

2. Install the package:

pip install -e .

3. Set up environment variables:

export NCBI_EMAIL="[e-mail]"  # Required for NCBI API calls
export NCBI_API_KEY="your_ncbi_api_key"     # Optional but recommended for higher rate limits

Optional: Neo4j Graph Database Setup

For pathway-aware analysis, you can optionally set up the Neo4j database:

1. Install Docker (if not already installed)

2. Start Neo4j container:

docker run -d --name neo4j-ksites -p 7687:7687 -p 7474:7474 -e NEO4J_AUTH=neo4j/password neo4j:latest

3. Ingest KEGG pathway data:

python -m k_sites.neo4j.ingest_kegg --taxid 9606

🚀 Usage

Command Line Interface

Basic usage:

k-sites --go-term GO:0006281 --organism "Homo sapiens" --output report.html

Advanced usage with all options:

k-sites --go-term GO:0006281 --organism 9606 --output results/report.html \
        --use-graph \
        --max-pleiotropy 5 \
        --evidence-filter experimental \
        --species-validation 9606 10090 10116 \
        --predict-phenotypes

Programmatic API

from k_sites.workflow.pipeline import run_k_sites_pipeline

results = run_k_sites_pipeline(
    go_term="GO:0006281",  # DNA repair
    organism="Homo sapiens",
    max_pleiotropy=3,
    use_graph=True,
    evidence_filter="experimental",
    species_validation=["9606", "10090"],
    predict_phenotypes=True
)

# Generate report
from k_sites.reporting.report_generator import generate_html_report
generate_html_report(results, "output_report.html")

⚙️ Configuration

Environment Variables

• NCBI_EMAIL: Your email address for NCBI API compliance (required)
• NCBI_API_KEY: NCBI API key for higher rate limits (optional)
• NEO4J_URI: Neo4j connection URI (default: bolt://localhost:7687)
• NEO4J_USER: Neo4j username (default: neo4j)
• NEO4J_PASSWORD: Neo4j password (default: password)

Parameters

Parameter	Description	Default
--go-term	GO term to analyze (e.g., "GO:0006281")	Required
--organism	Organism as TaxID or scientific name	Required
--output	Output HTML report path	Required
--use-graph	Enable Neo4j pathway analysis	Enabled if available
--max-pleiotropy	Maximum allowed pleiotropy score	3
--evidence-filter	Evidence type filter	"experimental"
--species-validation	Species for cross-validation	9606 10090 10116 7227 6239
--predict-phenotypes	Enable RAG-based phenotype prediction	Disabled

🏗️ Architecture

The K-Sites platform consists of several interconnected modules:

k_sites/
├── data_retrieval/     # GO term mapping, organism resolution
├── gene_analysis/      # Pleiotropy scoring
├── crispr_design/      # gRNA design and scoring
├── neo4j/             # Graph database integration
├── rag_system/        # Literature-based phenotype prediction
├── workflow/          # Pipeline orchestration
├── reporting/         # Report generation
└── tests/             # Unit tests

🧪 Testing

Run the test suite:

python -m pytest tests/

📄 License

MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🐛 Issues

If you encounter any issues, please file them in the Issues section of the repository.

🙏 Acknowledgments

• Thanks to the GO Consortium for gene ontology resources
• Thanks to KEGG for pathway data
• Thanks to NCBI for biological databases
• Thanks to the Neo4j community for graph database technology