kg_microbe.query_utils package

Submodules

kg_microbe.query_utils.duckdb_loader module

DuckDB database loader for KG-Microbe knowledge graph.

kg_microbe.query_utils.duckdb_loader.get_or_create_database(nodes_path='data/merged/merged-kg_nodes.tsv', edges_path='data/merged/merged-kg_edges.tsv', db_path='data/merged/kg-microbe.duckdb', force_reload=False)

Load or connect to a DuckDB database built from KGX TSV files.

Existing databases are reused only when their recorded source paths and content-sensitive fingerprints match both input files. Rebuilds happen at a temporary sibling path and replace the advertised database atomically.

Parameters:

  • nodes_path (Union[str, Path]) – Path to nodes TSV file.

  • edges_path (Union[str, Path]) – Path to edges TSV file.

  • db_path (Union[str, Path]) – Path to DuckDB database file.

  • force_reload (bool) – Force rebuild from TSV files.

Return type:

DuckDBPyConnection

Returns:

Open DuckDB connection.

kg_microbe.query_utils.organism_queries module

Organism-specific query functions for KG-Microbe.

kg_microbe.query_utils.organism_queries.get_media_composition(conn, medium_ids)

Get chemical composition of growth media (2-hop: medium → solution → chemical).

Parameters:

  • conn (DuckDBPyConnection) – DuckDB connection

  • medium_ids (List[str]) – List of medium IDs (e.g., [‘mediadive.medium:693’])

Return type:

DataFrame

Returns:

DataFrame with medium_id, chemical_count, chemicals columns

kg_microbe.query_utils.organism_queries.get_media_preferences(conn, taxon_id)

Get growth media preferences (grows in / doesn’t grow in).

BacDive and MediaDive emit growth-media edges with the METPO term in the predicate column and the relation column: METPO:2000517 (grows in) / METPO:2000518 (does not grow in). Measured on the 2026-09-10 outputs: 36,596 + 55,251 edges, every one predicate == relation; none carry biolink:located_in (the docs here and in the kg-query skill said otherwise, #539). The predicate is matched first; relation is a fallback for a graph built before the METPO predicate replaced biolink:located_in, so an older release still answers.

Parameters:

  • conn (DuckDBPyConnection) – DuckDB connection

  • taxon_id (str) – NCBITaxon ID

Return type:

Dict[str, List[Dict]]

Returns:

Dict with ‘grows_in’ and ‘no_growth’ lists

kg_microbe.query_utils.organism_queries.get_organism_traits(conn, taxon_id)

Get all direct trait edges from organism (1-hop).

Parameters:

  • conn (DuckDBPyConnection) – DuckDB connection

  • taxon_id (str) – NCBITaxon ID (e.g., ‘NCBITaxon:84112’)

Return type:

DataFrame

Returns:

DataFrame with predicate, object, object_name, category, source columns

kg_microbe.query_utils.organism_queries.get_strain_info(conn, taxon_id)

Get strain nodes linked to species via subclass_of.

Parameters:

  • conn (DuckDBPyConnection) – DuckDB connection

  • taxon_id (str) – NCBITaxon ID

Return type:

DataFrame

Returns:

DataFrame with strain IDs and names

kg_microbe.query_utils.organism_queries.query_organism_full(conn, organism_name)

Execute comprehensive organism query and return all information.

Parameters:

  • conn (DuckDBPyConnection) – DuckDB connection

  • organism_name (str) – Organism name to search

Return type:

Dict

Returns:

Dict with all query results

kg_microbe.query_utils.organism_queries.resolve_organism_name(conn, name)

Resolve organism name to NCBITaxon ID using fuzzy matching.

When multiple organisms match, the best-ranked candidate (exact name match, then synonym match, then substring match) is returned; remaining candidates are logged as a warning so callers can refine the search term.

Parameters:

  • conn (DuckDBPyConnection) – DuckDB connection

  • name (str) – Organism name to search

Return type:

Dict[str, str]

Returns:

Dict with ‘id’, ‘name’, ‘synonym’ keys

Raises:

ValueError – If no organism is found

kg_microbe.query_utils.utils module

Utility functions for formatting and displaying query results.

kg_microbe.query_utils.utils.format_organism_report(query_result)

Generate markdown report from organism query results.

Parameters:

query_result (Dict) – Dict from query_organism_full()

Return type:

str

Returns:

Markdown formatted report string

Module contents

KG-Microbe query utilities for DuckDB-based knowledge graph queries.

kg_microbe.query_utils.format_organism_report(query_result)

Generate markdown report from organism query results.

Parameters:

query_result (Dict) – Dict from query_organism_full()

Return type:

str

Returns:

Markdown formatted report string

kg_microbe.query_utils.get_or_create_database(nodes_path='data/merged/merged-kg_nodes.tsv', edges_path='data/merged/merged-kg_edges.tsv', db_path='data/merged/kg-microbe.duckdb', force_reload=False)

Load or connect to a DuckDB database built from KGX TSV files.

Existing databases are reused only when their recorded source paths and content-sensitive fingerprints match both input files. Rebuilds happen at a temporary sibling path and replace the advertised database atomically.

Parameters:

  • nodes_path (Union[str, Path]) – Path to nodes TSV file.

  • edges_path (Union[str, Path]) – Path to edges TSV file.

  • db_path (Union[str, Path]) – Path to DuckDB database file.

  • force_reload (bool) – Force rebuild from TSV files.

Return type:

DuckDBPyConnection

Returns:

Open DuckDB connection.

kg_microbe.query_utils.query_organism_full(conn, organism_name)

Execute comprehensive organism query and return all information.

Parameters:

  • conn (DuckDBPyConnection) – DuckDB connection

  • organism_name (str) – Organism name to search

Return type:

Dict

Returns:

Dict with all query results