Quick start

This walkthrough covers an oncology study from creation through mutation landscape analysis and optional AI interpretation.

1. Create a study

Click Create study from the oncology dashboard. Enter a name (for example IO cohort demo) and optional tumor type, cancer stage, treatment arm, or response status metadata.

2. Add samples and clinical data

Open the study Data page. Register samples with patient/sample identifiers, timepoints, and group labels. Add clinical endpoints (survival time, event status, treatment arm) when available.

For API smoke tests, confirm the metadata service is running:

curl http://localhost:8000/oncology/studies

3. Prepare a mutation MAF file

The mutation landscape pipeline accepts a MAF-style CSV. For a minimal test fixture, use the pattern from the test suite:

import pandas as pd

maf = pd.DataFrame({
    "Hugo_Symbol": ["TP53", "KRAS", "TP53", "PIK3CA"],
    "Tumor_Sample_Barcode": ["S1", "S1", "S2", "S2"],
    "Variant_Classification": [
        "Missense_Mutation", "Missense_Mutation",
        "Nonsense_Mutation", "Frame_Shift_Del",
    ],
    "Chromosome": ["17", "12", "17", "3"],
    "Start_Position": [7579472, 25398284, 7578406, 178936091],
    "Reference_Allele": ["C", "G", "C", "T"],
    "Tumor_Seq_Allele2": ["T", "A", "A", "TA"],
})
maf.to_csv("/tmp/cohort.maf", index=False)

4. Run mutation landscape

Dispatch a mutation landscape job from the Mutations page or directly via the analysis API:

curl -X POST http://localhost:8001/oncology/jobs/mutation-landscape \
  -H "Content-Type: application/json" \
  -d '{
    "study_id": "your-study-id",
    "parameters": {
      "mutation_path": "/tmp/cohort.maf",
      "panel_size_mb": 1.0,
      "top_genes": 10
    }
  }'

Poll until complete:

curl http://localhost:8001/oncology/jobs/{run_id}

Review TMB per sample, gene frequency table, oncoprint matrix, and mutational signature summary in the job result.

5. Run survival analysis (optional)

Prepare a clinical CSV with patient_id, time_to_event_days, and event_observed columns. Dispatch:

curl -X POST http://localhost:8001/oncology/jobs/survival \
  -H "Content-Type: application/json" \
  -d '{
    "study_id": "your-study-id",
    "parameters": {
      "clinical_path": "/tmp/clinical.csv",
      "stratify_by": "treatment_arm"
    }
  }'

6. Interpret (optional)

After one or more pipeline runs complete, launch interpretation with the source run IDs:

curl -X POST http://localhost:8001/oncology/jobs/interpret \
  -H "Content-Type: application/json" \
  -d '{
    "study_id": "your-study-id",
    "parameters": {
      "source_run_ids": ["onco-run-abc12345"],
      "interpretation_type": "summary"
    }
  }'

Requires Ollama configuration in backend-analysis — see the repo root ai.md.

Next steps

Key concepts
Data upload — samples, clinical endpoints, MAF, and repertoire formats
Pipelines reference — all available analysis steps

Menu

Documentation