Enrichment Sources¶

Graffold integrates with external biomedical databases to enrich knowledge graph entities with curated annotations, associations, and hierarchical relationships.

Open Targets Platform¶

Fetches drug-target-disease associations via the Open Targets GraphQL API.

What It Adds¶

Target → Disease association scores (0.0–1.0)
Evidence count per association
Data type breakdown (literature, genetic, clinical, etc.)
Known drugs for targets (phase, mechanism of action)

Usage¶

# CLI
graffold enrich-external --source opentargets -t ENSG00000141510 -t ENSG00000012048 -db mydb

# API
curl -X POST http://localhost:8000/v1/enrichment/opentargets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": ["ENSG00000141510"],
    "diseases": ["EFO_0000270"],
    "database": "mydb",
    "max_per_entity": 50
  }'

Python¶

from pipeline.processors.opentargets_integrator import OpenTargetsIntegrator

integrator = OpenTargetsIntegrator(graph_store=my_graph_store)
result = await integrator.enrich_graph(
    targets=["ENSG00000141510"],
    diseases=["EFO_0000270"],
)
print(f"{result.associations_fetched} associations → {result.relationships_created} edges")

UniProt¶

Fetches protein functional annotations from the UniProt REST API.

What It Adds¶

Full protein name and gene names
Function description
Subcellular location
GO terms (biological process, molecular function, cellular component)
Pathway involvement
Disease involvement
Keywords
Sequence length

Usage¶

from pipeline.processors.uniprot_integrator import UniProtIntegrator

integrator = UniProtIntegrator(db=my_database)
stats = await integrator.enrich_proteins(
    uniprot_ids=["P04637", "P38398", "P35354"]
)
print(f"{stats.proteins_enriched} proteins enriched")

Auto-detect mode (enriches all proteins missing annotations):

stats = await integrator.enrich_proteins(limit=500)

DisGeNET¶

Ingests gene-disease associations from DisGeNET TSV files.

What It Adds¶

Gene → Disease association scores (0.0–1.0)
Evidence index
Source classification (CURATED, LITERATURE, GWAS, ANIMAL)
Publication count per association

Usage¶

# CLI
graffold enrich-external --source disgenet -f data/disgenet_curated.tsv --min-score 0.5 -db mydb

# API
curl -X POST http://localhost:8000/v1/enrichment/disgenet \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "data/disgenet_curated.tsv",
    "database": "mydb",
    "min_score": 0.3,
    "source_filter": ["CURATED", "GWAS"]
  }'

Download DisGeNET Data¶

# Download from DisGeNET (requires free registration)
# https://www.disgenet.org/downloads
wget -O data/all_gene_disease_associations.tsv.gz \
  "https://www.disgenet.org/static/disgenet_ap1/files/downloads/all_gene_disease_associations.tsv.gz"
gunzip data/all_gene_disease_associations.tsv.gz

MONDO Disease Hierarchy¶

Builds parent-child disease relationships from the MONDO Disease Ontology.

What It Adds¶

IS_SUBTYPE_OF relationships between disease nodes
MONDO IDs assigned to disease nodes via name/synonym matching
Enables hierarchical queries ("heart disease" includes subtypes)

Usage¶

from pipeline.processors.disease_hierarchy_enricher import DiseaseHierarchyEnricher

enricher = DiseaseHierarchyEnricher(db=my_database, obo_path="data/mondo.obo")
stats = enricher.enrich()
print(f"{stats.hierarchy_edges_created} hierarchy edges, {stats.mondo_ids_assigned} IDs assigned")

Download MONDO¶

wget -O data/mondo.obo "http://purl.obolibrary.org/obo/mondo.obo"

Evidence Scoring¶

Classifies biomedical abstracts by study design and computes composite evidence quality scores.

Study Design Hierarchy¶

Design	Weight	Description
Randomized Controlled Trial	1.00	Gold standard
Meta-Analysis	0.95	Statistical combination of multiple studies
Systematic Review	0.90	Systematic search and synthesis
Cohort Study	0.70	Observational, following groups over time
Case-Control	0.60	Compares cases vs. controls
Observational	0.50	General observational
In Vitro	0.40	Laboratory experiments
Computational	0.35	Bioinformatics/modeling
Case Report	0.30	Individual patient descriptions

Usage¶

# CLI
graffold score-evidence "This randomized controlled trial enrolled 500 patients with heart failure."

# API
curl -X POST http://localhost:8000/v1/enrichment/score-evidence \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "abstracts": [
      {"text": "This meta-analysis pooled 25 studies...", "year": 2024},
      {"text": "We report a case of elevated troponin...", "year": 2020}
    ]
  }'

Python¶

from pipeline.processors.evidence_scorer import EvidenceScorer

scorer = EvidenceScorer(llm=None)  # Heuristic mode
score = scorer.score_evidence(abstract_text, publication_year=2024)

print(f"Design: {score.study_design.study_type}")
print(f"Composite: {score.composite_score:.3f}")
print(f"Tier: {score.quality_tier}")  # high / medium / low

Community Detection¶

Detects entity communities using Louvain algorithm and generates LLM summaries for the "global" query mode.

What It Adds¶

community_id property on entity nodes
CommunitySummary nodes with natural language descriptions
Enables global-mode queries that reason over community themes

Usage¶

from pipeline.processors.community_detector import CommunityDetector

detector = CommunityDetector(db=my_database, llm=my_llm, min_community_size=3)
result = detector.detect(generate_summaries=True)

print(f"{result.total_communities} communities (modularity={result.modularity:.3f})")

# Persist to graph
detector.write_community_ids(result.communities)
detector.write_summaries(result.communities)