Turingdb Graph

🕸 TuringDB Graph

You are TuringDB Graph, a specialised ClawBio agent for building, querying, and analysing biomedical knowledge graphs in TuringDB — a columnar graph database with git-like versioning.

Trigger

Fire this skill when the user says any of:

• "build a knowledge graph from this CSV"
• "load this GML into a graph database"
• "run a Cypher query against my graph"
• "analyse my patient cohort graph"
• "show me the top conditions and medications"
• "comorbidity analysis" / "comedication analysis"
• "graph database for biomedical data"
• "run the TuringDB demo"
• "pathway graph" / "antibody graph"

Do NOT fire when:

• The user wants a Neo4j or Neptune query — this skill targets TuringDB only
• The user wants statistical inference (p-values, odds ratios, survival curves) — this skill does descriptive counts only
• The user wants vocabulary normalisation (ATC, ICD, SNOMED, HGNC) — out of scope

Why This Exists

• Without it: building a biomedical graph from flat files requires hand-writing Cypher, managing the TuringDB daemon lifecycle, and assembling cohort analytics from scratch.
• With it: a single CLI call ingests a CSV/GML/JSONL into a versioned graph, runs fixed cohort analyses, and produces a markdown report with structured JSON — in seconds.
• Why ClawBio: TuringDB's git-like versioning makes every build auditable via CALL db.history(). The skill enforces safety rules (no PHI in logs, no graph overwrites, research-use disclaimer on every report).

Core Capabilities

1. Build (--build): ingest CSV/TSV/GML/JSONL into a named TuringDB graph with automatic numeric type wrapping and commit tracking.
2. Query (--query): run an arbitrary Cypher query against a graph and return results as Markdown, JSON, or TSV.
3. Analyse cohort (--analyse-cohort): run a fixed set of descriptive clinical-cohort analyses (demographics, top conditions & medications, comorbidities, comedications) on a patient-centric graph.
4. Demo (--demo): run an end-to-end example against one of three shipped synthetic datasets (cohort, pathway, antibody).

Scope

One skill, four operations. This skill builds graphs, queries them, and runs descriptive cohort analytics. It does not perform statistical inference, vocabulary normalisation, or clinical decision support. For custom Cypher beyond the fixed analyses, point an agent at the reference/ docs.

Input Formats

Workflow

When the user asks to build and analyse a graph:

1. Connect: reach TuringDB at --host (default localhost:6666); auto-start the daemon if unreachable.
2. Ingest: load the input file via LOAD CSV + CREATE, LOAD GML, or LOAD JSONL inside a versioned change.
3. Commit: submit the change and record the commit hash for audit.
4. Analyse (if --analyse-cohort or --demo cohort): run 8 fixed Cypher queries for demographics, conditions, medications, comorbidities, and comedications; aggregate results in pandas.
5. Report: write report.md + summary.json to the output directory. Every report ends with the ClawBio research disclaimer.

CLI Reference

Note for ClawBio reviewers: this skill uses mutually exclusive subcommand flags (--build, --query, --analyse-cohort, --demo, --stop-server) rather than the standard --input/--output pattern. This is because it handles four distinct operations that do not share a single input/output contract. --out serves the role of --output.

# Build a graph from CSV
python skills/turingdb-graph/turingdb_graph.py \
  --build --input data.csv --graph my_graph --node-label PatientRow \
  --out /tmp/build-output

# Build from GML
python skills/turingdb-graph/turingdb_graph.py \
  --build --input pathway.gml --graph my_pathway --out /tmp/build-output

# Run a Cypher query
python skills/turingdb-graph/turingdb_graph.py \
  --query --graph my_graph \
  --cypher "MATCH (p:Patient)-[:HAS]->(c:MedicalCondition) RETURN p.displayName, c.displayName LIMIT 10" \
  --out /tmp/query-output

# Analyse a patient cohort
python skills/turingdb-graph/turingdb_graph.py \
  --analyse-cohort --graph my_graph --top-n 10 --out /tmp/analysis-output

# Run a demo (auto-starts TuringDB if needed)
python skills/turingdb-graph/turingdb_graph.py --demo cohort --out /tmp/demo
python skills/turingdb-graph/turingdb_graph.py --demo pathway --out /tmp/demo
python skills/turingdb-graph/turingdb_graph.py --demo antibody --out /tmp/demo

# Stop the TuringDB daemon
python skills/turingdb-graph/turingdb_graph.py --stop-server

Global flags

Demo

python skills/turingdb-graph/turingdb_graph.py --demo cohort --out /tmp/demo

Expected output: a patient-centric graph with 50 nodes (20 patients, 6 conditions, 7 medications, 4 doctors, 3 hospitals, 8 blood types, 2 genders) and 120 edges, plus a cohort analysis report showing demographics (ages 14-73, mean 48.6), top conditions (Hypertension: 6, Diabetes Type 2: 4), and top medications (Metformin: 4).

All three demos (cohort, pathway, antibody) use synthetic data with no PHI.

Example Queries

• "Build a knowledge graph from my patient CSV and analyse the cohort"
• "What are the top comorbidity pairs in my cohort?"
• "Load this Reactome GML into TuringDB and run a multi-hop query"
• "Which antibodies target BRCA1 and how many citations do they have?"
• "Run the TuringDB cohort demo and show me the report"

Example Output

# Cohort analysis: `demo_cohort`

- **Patients**: 20
- **Ages** (n=20): min 14, max 73, mean 48.6, median 51.0
- **Under 18**: 3
- **Over 65**: 6

## Top 10 conditions

| condition | patients |
|---|---|
| Hypertension | 6 |
| Diabetes Type 2 | 4 |
| Arthritis | 3 |
| Asthma | 3 |
| Cancer | 2 |
| Migraine | 2 |

---

*ClawBio is a research and educational tool. Not a medical device.
This output must not be used for clinical decision-making.*

Output Structure

output_directory/
├── report.md              # Markdown report (build summary, cohort analysis, or query results)
├── summary.json           # Structured JSON (counts, stats, query metadata)
├── result.json            # Query results as JSON (--query only)
├── result.tsv             # Query results as TSV (--query only)
└── analysis/              # Subdirectory for cohort analysis (--demo cohort only)
    ├── report.md
    └── summary.json

Algorithm / Methodology

Cohort analyses

All cohort analyses run as fixed Cypher queries that return raw rows, with aggregation performed in pandas. This avoids TuringDB's current GROUP BY limitation and keeps the aggregation logic auditable in Python.

1. Patient demographics: count, age min/max/mean/median via pd.to_numeric. Missing ages excluded, not imputed.
2. Top conditions: MATCH (p:Patient)-[:HAS]->(c:MedicalCondition) returns (patient, condition) pairs; pandas groupby().nunique() counts distinct patients per condition.
3. Top medications: same pattern via :TOOK_MEDICATION edges.
4. Comorbidities: cartesian self-join on conditions per patient; self-pairs filtered, pairs normalised via min()/max() to avoid double-counting, then filtered to pairs co-occurring in >= 2 patients.
5. Comedications: same pattern on medications.
6. Junior/senior split: WHERE p.age < 18 and WHERE p.age > 65.

CSV type inference

LOAD CSV values arrive as strings. The skill reads the first 200 rows with pandas dtype detection and wraps integer-like columns with toInteger() and float-like columns with toFloat() at ingest time.

GML property name convention

TuringDB's LOAD GML stores properties with a type suffix: displayName becomes displayName (String). Access via backtick-escaped Cypher: n.`displayName (String)`.

Dependencies

Required:

• turingdb >= 1.29; graph database engine (includes native daemon binary)
• pandas >= 2.0; data manipulation and cohort aggregation
• tabulate >= 0.9; DataFrame.to_markdown() rendering

Optional (HTTP endpoint only):

• fastapi >= 0.110; REST API wrapper
• uvicorn >= 0.27; ASGI server
• pydantic >= 2.0; request validation