Biomedical researchers and computational biologists frequently need to trace complex mechanistic connections across diseases, molecular targets, clinical phenotypes, and pharmacological agents. Running a targeted biomedical knowledge graph query allows you to move beyond isolated literature searches and inspect interconnected biological relationships directly. Precision Medicine Knowledge Graph (PrimeKG) integrates diverse biomedical datasets into a structured network, making it a valuable resource for downstream computational workflows and reasoning agents.

In this practical guide, you will learn how to prepare identifiers, establish a reproducible querying environment, write traversal routines, and evaluate multi-hop biological relationships. This tutorial presents architectural patterns and planning procedures rather than benchmarked execution claims.

---

1. Resolve Biological Identifiers Before Querying

A primary source of silent failures in graph querying is vocabulary mismatch. PrimeKG harmonizes entities across distinct vocabularies, such as MONDO for disease phenotypes, Entrez for genes and proteins, DrugBank for pharmaceutical compounds, and the Human Phenotype Ontology (HPO) for clinical traits.

If you initiate a query using colloquial disease names or legacy gene symbols, your queries will likely return empty subgraphs or ambiguous matches. Before querying:

  • Convert free-text clinical descriptions into normalized ontology terms.
  • Use an automated entity resolution step—such as the ontology-term-resolution skill—to map input entities to canonical identifiers before building graph lookups.
  • Maintain a local mapping table to store the input synonym alongside the resolved identifier and source vocabulary namespace for auditing purposes.

For example, when studying a therapeutic mechanism, resolve both the drug's common name to its official DrugBank accession and the target condition to its MONDO identifier before sending queries to graph indexes.

---

2. Structure Your Agent Tooling and Execution Workspace

When integrating knowledge graph lookups into automated agent workflows, structure your tooling cleanly. The Agent Skills open format provides an organized standard: each skill resides in a dedicated folder containing a SKILL.md file with YAML frontmatter defining name and description fields, alongside optional scripts and reference files. Autonomous agents discover available operations by inspecting SKILL.md and load referenced resources on demand.

To support consistent execution across development workstations and high-performance computing clusters:

  • Use containers to preserve system-level dependencies. Docker packages software and underlying system libraries into portable images. On shared HPC clusters where users lack root access, Singularity/Apptainer serves as the standard alternative because it runs without root privileges.
  • Pin your code explicitly using git commits. Recording the exact git commit hash via git rev-parse HEAD captures the exact software version used for an analysis far more reliably than volatile branch names or informal release tags.

To structure operations, integrate the primekg skill inside your agent's workspace to handle the core dataset interactions.

---

## Setting Up Your Biomedical Knowledge Graph Query Environment

Knowledge graph interactions typically load edge tables into an in-memory graph representation (such as NetworkX or an indexed columnar database) or query an external graph database engine.

Below is an operational example of a Python script designed for local graph querying. It records the environment's git commit hash, loads pre-filtered edge records, and extracts paths between a designated drug and disease entity:

# Capture the exact repository commit state before running the query
git rev-parse HEAD > analysis_environment.commit
import json
import networkx as nx
import pandas as pd

def run_targeted_query(edge_table_path: str, source_node: str, target_node: str):
    # Load edge records containing standardized identifiers
    edges_df = pd.read_csv(edge_table_path, sep="\t", low_memory=False)
    
    # Construct an undirected multigraph to preserve multiple relation types
    G = nx.MultiGraph()
    for _, row in edges_df.iterrows():
        G.add_edge(
            row["x_id"], 
            row["y_id"], 
            relation=row["relation"], 
            display_relation=row["display_relation"]
        )
        
    if not (G.has_node(source_node) and G.has_node(target_node)):
        return {"status": "error", "message": "One or both nodes missing from graph."}
    
    # Retrieve short paths connecting source and target
    paths = []
    try:
        raw_paths = nx.all_shortest_paths(G, source=source_node, target=target_node)
        for path in raw_paths:
            path_details = []
            for i in range(len(path) - 1):
                edge_data = G.get_edge_data(path[i], path[i+1])
                path_details.append({
                    "from": path[i],
                    "to": path[i+1],
                    "edge_attributes": edge_data
                })
            paths.append(path_details)
    except nx.NetworkXNoPath:
        return {"status": "no_path_found", "paths": []}
        
    return {"status": "success", "paths": paths}

if __name__ == "__main__":
    # Example invocation using standardized identifiers
    # Replace with resolved IDs (e.g., DrugBank and MONDO codes)
    result = run_targeted_query(
        edge_table_path="primekg_edges.tsv", 
        source_node="DRUGBANK:DB00001", 
        target_node="MONDO:0005010"
    )
    print(json.dumps(result, indent=2))

---

3. Extract Subgraphs and Interpret Path Semantics

Querying a graph is rarely just about checking whether an edge exists. In translational biology, you must evaluate path length, intermediate node types, and edge directionality:

  1. Direct Associations: Direct edges typically denote well-characterized indications, contraindications, or binding interactions. Verify whether the relation represents an approved clinical indication versus an off-label or experimental observation.
  2. Intermediate Biological Links: If no direct edge exists, perform bounded breadth-first searches or shortest-path traversals. Intermediate paths often surface mechanism-of-action hypotheses (e.g., drug binds to protein target, which participates in a biological pathway associated with a disease phenotype).
  3. Relation Signs: Treat edge types carefully. A path passing through an "inhibitor" edge followed by an "upregulates" edge conveys an entirely different biological meaning than an uninterrupted chain of activation events.

---

4. Cross-Reference Paths with Federated Reasoners

Knowledge graphs compiled from heterogeneous literature and database dumps may contain outdated associations, data curation artifacts, or ambiguous clinical indications.

Whenever your traversal generates a biological lead or hypothesis, corroborate the findings against complementary translational engines. You can query external biomedical reasoners such as ncats-arax to validate whether independent knowledge sources, clinical databases, and automated biomedical reasoning pipelines corroborate the retrieved connections. Comparing PrimeKG subgraph topologies with ARAX reasoning outputs reduces false-positive interpretations stemming from graph assembly quirks.

---

Checks Before You Trust the Result

Before integrating query results into experimental designs, computational pipelines, or publications, perform these verification checks:

  • Verify ID Canonicalization: Ensure that every source, intermediate, and target identifier matches the exact vocabulary version intended.
  • Inspect Edge Semantics: Distinguish therapeutic indications from contraindications. Some biomedical graphs store both under generic disease-drug links distinguished only by specific edge attributes.
  • Examine Intermediate Hub Nodes: Check if your extracted shortest paths traverse ubiquitous "hub" proteins (such as widespread housekeeping genes or common general phenotypes). Hub-mediated paths frequently reflect literature bias rather than targeted biological mechanisms.
  • Track Provenance and Commits: Ensure that your analysis script outputs the active container hash and the commit hash from git rev-parse HEAD alongside the raw query outputs.

---

This guide provides a structured workflow for planning and executing biomedical knowledge graph queries rather than an empirical performance assessment. To explore the interfaces, file conventions, and parameter configurations for the skills discussed here, consult the documentation pages for primekg, ontology-term-resolution, and ncats-arax directly on ScienceSkills before deploying queries in your pipeline.