USER_GUIDE.md

# Cancer@Home v2 - User Guide

## Table of Contents
1. [Introduction](#introduction)
2. [System Architecture](#system-architecture)
3. [Getting Started](#getting-started)
4. [Dashboard Guide](#dashboard-guide)
5. [Working with Data](#working-with-data)
6. [Analysis Pipeline](#analysis-pipeline)
7. [Advanced Usage](#advanced-usage)

---

## Introduction

Cancer@Home v2 is a distributed computing platform for cancer genomics research that combines:
- **BOINC**: Distributed computing for computationally intensive tasks
- **GDC Portal**: Access to comprehensive cancer genomics datasets
- **Neo4j**: Graph database for modeling complex relationships
- **Bioinformatics Pipeline**: FASTQ processing, BLAST alignment, and variant calling

### Key Features
✓ Interactive web dashboard  
✓ Real-time graph visualization  
✓ GraphQL API for flexible data queries  
✓ Distributed task processing  
✓ Cancer genomics data integration  

---

## System Architecture

```
┌─────────────────────────────────────────────────┐
│              Web Dashboard (Port 5000)          │
│  Dashboard | Neo4j Viz | BOINC | GDC | Pipeline│
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────┐
│           FastAPI Backend (REST + GraphQL)      │
└─────┬──────┬──────┬──────┬──────┬──────────────┘
      │      │      │      │      │
   ┌──┴─┐ ┌──┴─┐ ┌──┴─┐ ┌──┴─┐ ┌──┴──────┐
   │Neo4j│ │BOINC│ │GDC │ │FASTQ│ │BLAST/VCF│
   │7687 │ │Client│ │API │ │Proc │ │ Caller  │
   └─────┘ └─────┘ └────┘ └─────┘ └─────────┘
```

---

## Getting Started

### Quick Installation (5 minutes)

**Windows:**
```powershell
.\setup.ps1
python run.py
```

**Linux/Mac:**
```bash
./setup.sh
python run.py
```

### Access Points
- **Main Application**: http://localhost:5000
- **API Documentation**: http://localhost:5000/docs
- **GraphQL Playground**: http://localhost:5000/graphql
- **Neo4j Browser**: http://localhost:7474 (neo4j/cancer123)

---

## Dashboard Guide

### 1. Overview Tab
Shows key statistics:
- Total genes in database
- Total mutations identified
- Number of patients
- Cancer types catalogued

**Chart**: Mutation distribution across cancer types

### 2. Neo4j Visualization Tab
Interactive graph showing:
- **Blue nodes**: Genes (TP53, BRCA1, KRAS, etc.)
- **Purple nodes**: Patients
- **Pink nodes**: Cancer types
- **Lines**: Relationships between entities

**Navigation**:
- Click and drag nodes to rearrange
- Hover over nodes for details
- Zoom in/out with mouse wheel

### 3. BOINC Tasks Tab
Manage distributed computing workloads:

**Submit Task**:
1. Select task type (Variant Calling, BLAST, Alignment)
2. Enter input file path
3. Click "Submit Task"

**Monitor Tasks**:
- View all tasks with status (Pending, Running, Completed)
- See task creation time and type
- Check overall statistics

### 4. GDC Data Tab
Browse available cancer projects:
- TCGA-BRCA: Breast Cancer (1,098 cases)
- TCGA-LUAD: Lung Adenocarcinoma (585 cases)
- TCGA-COAD: Colon Adenocarcinoma (461 cases)
- TCGA-GBM: Glioblastoma (617 cases)
- TARGET-AML: Acute Myeloid Leukemia (238 cases)

Click on a project to explore available datasets.

### 5. Pipeline Tab
Quick access to bioinformatics tools:
- **FASTQ QC**: Quality control for sequencing data
- **BLAST Search**: Sequence alignment and homology
- **Variant Calling**: Identify genetic variants

---

## Working with Data

### Querying with GraphQL

Access the GraphQL playground at http://localhost:5000/graphql

**Example 1: Find mutations in TP53 gene**
```graphql
query {
  mutations(gene: "TP53") {
    mutation_id
    chromosome
    position
    consequence
  }
}
```

**Example 2: Get patient information**
```graphql
query {
  patients(project_id: "TCGA-BRCA", limit: 10) {
    patient_id
    age
    gender
    vital_status
  }
}
```

**Example 3: Cancer statistics**
```graphql
query {
  cancerStatistics(cancer_type_id: "BRCA") {
    total_patients
    total_mutations
    avg_mutations_per_patient
  }
}
```

### Using the REST API

**Get database summary:**
```bash
curl http://localhost:5000/api/neo4j/summary
```

**Search GDC files:**
```bash
curl "http://localhost:5000/api/gdc/files/TCGA-BRCA?limit=10"
```

**Submit BOINC task:**
```bash
curl -X POST http://localhost:5000/api/boinc/submit \
  -H "Content-Type: application/json" \
  -d '{"workunit_type": "variant_calling", "input_file": "data/sample.fastq"}'
```

---

## Analysis Pipeline

### 1. FASTQ Processing

**Quality Control:**
```python
from backend.pipeline import FASTQProcessor

processor = FASTQProcessor()
stats = processor.calculate_statistics("input.fastq")
print(f"Total reads: {stats['total_reads']}")
print(f"Average quality: {stats['avg_quality']}")
```

**Filter by quality:**
```python
filtered = processor.quality_filter("input.fastq", "filtered.fastq")
print(f"Pass rate: {filtered['pass_rate']:.2%}")
```

### 2. BLAST Alignment

**Run BLAST search:**
```python
from backend.pipeline import BLASTRunner

blast = BLASTRunner()
results = blast.run_blastn("query.fasta")
hits = blast.parse_results(results)

print(f"Found {len(hits)} alignments")
```

**Filter high-quality hits:**
```python
filtered_hits = blast.filter_hits(hits, min_identity=0.95)
```

### 3. Variant Calling

**Identify variants:**
```python
from backend.pipeline import VariantCaller

caller = VariantCaller()
vcf_file = caller.call_variants("alignment.bam", "reference.fa")
variants = caller.filter_variants(vcf_file, min_quality=30)

print(f"Identified {len(variants)} high-quality variants")
```

**Find cancer-associated variants:**
```python
from backend.pipeline import VariantAnalyzer

analyzer = VariantAnalyzer()
cancer_variants = analyzer.identify_cancer_variants(variants)
tmb = analyzer.calculate_mutation_burden(variants)

print(f"Cancer variants: {len(cancer_variants)}")
print(f"Tumor Mutation Burden: {tmb:.2f} mutations/Mb")
```

---

## Advanced Usage

### Custom Neo4j Queries

**Direct Cypher queries:**
```python
from backend.neo4j import DatabaseManager

db = DatabaseManager()

# Find patients with TP53 mutations
query = """
MATCH (p:Patient)-[:HAS_MUTATION]->(m:Mutation)-[:AFFECTS]->(g:Gene {symbol: 'TP53'})
RETURN p.patient_id, m.position, m.consequence
"""

results = db.execute_query(query)
for result in results:
    print(result)

db.close()
```

### Batch Data Import

**Import GDC data:**
```python
from backend.gdc import GDCClient
from backend.neo4j import DataImporter

# Download mutation data
gdc = GDCClient()
files = gdc.get_mutation_data("TCGA-BRCA", limit=10)

for file in files:
    gdc.download_file(file.file_id)

# Import to Neo4j
importer = DataImporter()
importer.import_gdc_data(files)
```

### Custom BOINC Tasks

**Submit custom analysis:**
```python
from backend.boinc import BOINCClient

client = BOINCClient()

# Submit multiple tasks
input_files = ["sample1.fastq", "sample2.fastq", "sample3.fastq"]
task_ids = []

for file in input_files:
    task_id = client.submit_task("variant_calling", file)
    task_ids.append(task_id)

# Monitor progress
for task_id in task_ids:
    status = client.get_task_status(task_id)
    print(f"Task {task_id}: {status.status}")
```

### Configuration Customization

Edit `config.yml`:

```yaml
neo4j:
  uri: "bolt://localhost:7687"
  password: "your_password"

gdc:
  download_dir: "./data/gdc"
  max_retries: 3

pipeline:
  fastq:
    quality_threshold: 25  # Increase quality threshold
    min_length: 75         # Increase minimum read length
  
  blast:
    evalue: 0.0001         # More stringent e-value
    num_threads: 8         # Use more CPU cores
```

---

## Troubleshooting

### Neo4j Connection Issues
```bash
# Check Neo4j status
docker ps | grep neo4j

# Restart Neo4j
docker-compose restart neo4j

# View Neo4j logs
docker-compose logs neo4j
```

### Memory Issues
Increase Docker memory allocation:
1. Open Docker Desktop Settings
2. Resources → Memory
3. Increase to at least 8GB
4. Click "Apply & Restart"

### API Errors
Check logs:
```bash
# View application logs
cat logs/cancer_at_home.log

# Follow logs in real-time
tail -f logs/cancer_at_home.log
```

---

## Best Practices

1. **Data Management**: Regularly clean up downloaded data to free space
2. **Task Monitoring**: Check BOINC tasks periodically for failures
3. **Database Backup**: Backup Neo4j data volume regularly
4. **Resource Limits**: Monitor system resources when running large analyses
5. **API Rate Limits**: Be mindful of GDC API rate limits for bulk downloads

---

## Support & Resources

- **Documentation**: See README.md and QUICKSTART.md
- **API Reference**: http://localhost:5000/docs
- **GraphQL Examples**: See GRAPHQL_EXAMPLES.md
- **Logs**: Check `logs/cancer_at_home.log`

### Useful Cypher Queries

**Most common mutations:**
```cypher
MATCH (m:Mutation)<-[:HAS_MUTATION]-(p:Patient)
WITH m, count(p) as patient_count
RETURN m.mutation_id, patient_count
ORDER BY patient_count DESC
LIMIT 10
```

**Genes with most mutations:**
```cypher
MATCH (g:Gene)<-[:AFFECTS]-(m:Mutation)
WITH g, count(m) as mutation_count
RETURN g.symbol, mutation_count
ORDER BY mutation_count DESC
LIMIT 10
```

**Patient mutation profile:**
```cypher
MATCH (p:Patient {patient_id: 'TCGA-A1-001'})-[:HAS_MUTATION]->(m:Mutation)-[:AFFECTS]->(g:Gene)
RETURN g.symbol, m.consequence, m.position
```