Database Queries

This vignette demonstrates how to query each database module in the UniTCM platform.

Herb Explorer

Search and filter herbs

# Text search
herbs <- search_herbs(q = "ginseng")

# Multi-value faceted filters
herbs <- search_herbs(
  flavors = c("sweet", "bitter"),
  properties = "warm",
  toxicity = "non-toxic"
)

# View available filter values
facets <- fetch_herb_facets()
facets$toxicity
facets$meridians

Herb details and compounds

UniTCM IDs are flexible: all get_* and export_* functions accept either the prefixed display form shown on the website (e.g. "UNITCM_H001", "UNITCM_I00001") or the bare numeric ID (e.g. "1", 1L). The package normalizes them internally before calling the API.

herb <- get_herb("UNITCM_H001")
herb$herb_english_name
herb$efficacy

# Get compounds found in this herb
compounds <- get_herb_compounds("UNITCM_H001", all_pages = TRUE)
head(compounds)

Export data

export_herbs(q = "ginseng", file = "ginseng_herbs.csv")
export_herb_compounds("UNITCM_H001", file = "ginseng_compounds.csv")

Ingredient Explorer

Search compounds by properties

# Drug-like compounds with molecular weight 200-500
compounds <- search_compounds(
  mw_min = 200, mw_max = 500,
  lipinski = "pass",
  is_drug = TRUE
)

# Get facet statistics
facets <- fetch_compound_facets()
facets$mw_range

Compound details, ADMET, and targets

# Full compound record
compound <- get_compound("UNITCM_I00001")
compound$component_name
compound$xref$pubchem_cid

# ADMET predictions (~90 endpoints)
admet <- get_compound_admet("UNITCM_I00001")
admet$caco2_permeability
admet$hia

# Predicted targets (DrugCLIP deep learning)
targets_dc <- get_compound_targets("UNITCM_I00001", method = "drugclip")

# ChEMBL similarity-based targets
targets_ch <- get_compound_targets("UNITCM_I00001", method = "chembl")

# Both sources combined
targets_all <- get_compound_targets("UNITCM_I00001", method = "both")
table(targets_all$source)

Disease-Formula Atlas

Search formulas by disease

# Search by text
formulas <- search_formulas(q = "insomnia")

# Filter by ICD-11 classification
formulas <- search_formulas(
  level1 = "Neoplasms",
  mapping_confidence = c("high", "medium")
)

# Browse the disease classification tree
tree <- fetch_disease_tree()

# Available filter options
list_book_sources()
list_origin_sources()
list_dosage_forms()

Formula details and doses

formula <- get_formula(1)
formula$formula_name
formula$efficacy

# Herb composition and dosage
doses <- get_formula_doses(1)
doses

TCM Ontology

Search and navigate the ontology

# Full-text search
results <- search_ontology("Qi stagnation")

# Get entity with relations
entity <- get_ontology_entity("TCM_0001")
entity$ancestors
entity$children
entity$external_mappings

# Navigate the hierarchy
children <- get_ontology_children("TCM_0001")
ancestors <- get_ontology_ancestors("TCM_0001")
descendants <- get_ontology_descendants("TCM_0001", max_level = 2)

Ontology tree and statistics

# Fetch tree at depth 2
tree <- fetch_ontology_tree(depth = 2)

# Statistics
stats <- fetch_ontology_stats()
stats$total_entities

# Top-level categories
categories <- list_ontology_categories()

Cross-database mapping

# Find TCM entities mapped to a MeSH term
mapped <- search_ontology_mapping("MeSH", "D008516")

# Export ontology
export_ontology("csv", file = "tcm_ontology.csv")
export_ontology("json", depth = 3, file = "tcm_ontology.json")

MIDAS Gene-Disease Analysis

Gene-to-disease and disease-to-gene

# Which diseases are associated with these genes?
g2d <- query_gene_diseases(c("TP53", "BRCA1", "EGFR"))
g2d
attr(g2d, "gene_mapping")

# Which genes are associated with breast cancer?
d2g <- query_disease_genes("breast cancer")
d2g
attr(d2g, "matched_diseases")

Disease enrichment analysis

gene_list <- c("TP53", "BRCA1", "EGFR", "VEGFA", "MYC", "KRAS")
enrichment <- query_disease_enrichment(
  gene_list,
  p_value_cutoff = 0.05,
  correction_method = "fdr"
)
enrichment
attr(enrichment, "total_significant")

Utility functions

# Convert mixed gene identifiers
convert_gene_ids(c("TP53", "7157", "ENSG00000141510"))

# Autocomplete disease names
autocomplete_disease("breast")

# Available data sources
fetch_midas_sources()

# Database statistics
fetch_midas_stats()