drugannotR provides coordinate-level pharmacological
annotation. It reports that a region overlaps a gene feature or an
explicitly mapped variant connected to a drug relationship. It does not
infer that the region is functional, predict response, rank drugs, or
make treatment recommendations.
The evidence chain is:
region -> genomic feature -> gene -> drug-gene relationship -> source recordEvery result retains the genomic coordinates, controlled relationship category, coordinate evidence scope, and source provenance.
The canonical relationship categories are target,
pharmacodynamics, metabolism,
transport, carrier, efficacy,
toxicity, dosage, Other,
resistance, and exposure.
This local example uses a small user-curated table:
records <- data.frame(
drug_id = c("drug:clopidogrel", "drug:clopidogrel"),
drug_name = c("clopidogrel", "clopidogrel"),
gene_symbol = c("CYP2C19", "P2RY12"),
relationship_category = c("metabolism", "target"),
evidence_level = c("1A", NA),
evidence_scope = c("exact_variant", "gene_association"),
source = c("example PGx source", "example target source"),
source_record_id = c("pgx:1", "target:1"),
variant_id = c("rs-example", NA)
)
drug_sets <- buildDrugGeneSets(
sources = "custom",
source_data = list(custom = records)
)
drug_sets## DataFrame with 2 rows and 15 columns
## drug_id drug_name gene_id gene_symbol
## <character> <character> <character> <character>
## custom.1 drug:clopidogrel clopidogrel NA CYP2C19
## custom.2 drug:clopidogrel clopidogrel NA P2RY12
## relationship_category interaction_type direction phenotype
## <character> <character> <character> <character>
## custom.1 metabolism NA NA NA
## custom.2 target NA NA NA
## phenotype_category evidence_level evidence_scope
## <character> <character> <character>
## custom.1 NA 1A exact_variant
## custom.2 NA NA gene_association
## source source_record_id genome_build variant_id
## <character> <character> <character> <character>
## custom.1 example PGx source pgx:1 NA rs-example
## custom.2 example target source target:1 NA NAClinPGx/PharmGKB, DGIdb, and DrugCentral public tables are fetched
and cached when no local entry is supplied. DGIdb and DrugCentral claims
remain in the target category; target interaction data are
not promoted to efficacy or toxicity:
A local summaryAnnotations.zip can be supplied through
source_data for a fixed snapshot. ClinPGx annotations with
multiple supported phenotype categories are expanded into distinct
relationship rows. ClinPGx phenotype categories that are not assigned to
a supported pharmacological relationship are retained as
Other.
A gene model can be a TxDb or a GRanges. An
untyped GRanges represents gene bodies. Here a compact
model keeps the example self-contained:
gene_model <- GRanges(
seqnames = c("chr10", "chr3"),
ranges = IRanges(
start = c(94760000, 151337000),
end = c(94860000, 151384000)
),
strand = c("+", "-"),
gene_symbol = c("CYP2C19", "P2RY12")
)
variant_ranges <- GRanges(
seqnames = "chr10",
ranges = IRanges(94781859, 94781859),
variant_id = "rs-example"
)
drug_ranges <- mapDrugGenes(
drug_sets,
genome = "GRCh38",
gene_model = gene_model,
features = c("gene_body", "promoter"),
variant_ranges = variant_ranges
)
drug_ranges## GRanges object with 1654 ranges and 26 metadata columns:
## seqnames ranges strand | drug_id drug_name
## <Rle> <IRanges> <Rle> | <character> <character>
## [1] chr10 94758000-94760499 + | <NA> mephenytoin
## [2] chr10 94758000-94760499 + | <NA> clopidogrel
## [3] chr10 94758000-94760499 + | <NA> mephenytoin
## [4] chr10 94758000-94760499 + | <NA> clobazam
## [5] chr10 94758000-94760499 + | <NA> clobazam
## ... ... ... ... . ... ...
## [1650] chr3 151383501-151386000 - | DrugCentral:1034 epoprostenol
## [1651] chr3 151383501-151386000 - | DrugCentral:2657 ticlopidine
## [1652] chr3 151383501-151386000 - | DrugCentral:4113 prasugrel
## [1653] chr3 151383501-151386000 - | DrugCentral:4184 ticagrelor
## [1654] chr3 151383501-151386000 - | DrugCentral:5006 cangrelor
## gene_id gene_symbol relationship_category interaction_type
## <character> <character> <character> <character>
## [1] <NA> CYP2C19 dosage clinical_summary_ann..
## [2] <NA> CYP2C19 toxicity clinical_summary_ann..
## [3] <NA> CYP2C19 metabolism clinical_summary_ann..
## [4] <NA> CYP2C19 dosage clinical_summary_ann..
## [5] <NA> CYP2C19 efficacy clinical_summary_ann..
## ... ... ... ... ...
## [1650] <NA> P2RY12 target <NA>
## [1651] <NA> P2RY12 target antagonist
## [1652] <NA> P2RY12 target antagonist
## [1653] <NA> P2RY12 target negative allosteric ..
## [1654] <NA> P2RY12 target antagonist
## direction phenotype phenotype_category evidence_level
## <character> <character> <character> <character>
## [1] <NA> <NA> dosage 3
## [2] <NA> Acute coronary syndr.. toxicity 3
## [3] <NA> <NA> metabolism 3
## [4] <NA> Epilepsy dosage 3
## [5] <NA> Epilepsy efficacy 3
## ... ... ... ... ...
## [1650] <NA> <NA> <NA> <NA>
## [1651] <NA> <NA> <NA> <NA>
## [1652] <NA> <NA> <NA> <NA>
## [1653] <NA> <NA> <NA> <NA>
## [1654] <NA> <NA> <NA> <NA>
## evidence_scope source source_record_id genome_build
## <character> <character> <character> <character>
## [1] regulatory_overlap ClinPGx 655387767 GRCh38
## [2] regulatory_overlap ClinPGx 655386913 GRCh38
## [3] regulatory_overlap ClinPGx 1447983177 GRCh38
## [4] regulatory_overlap ClinPGx 1451245620 GRCh38
## [5] regulatory_overlap ClinPGx 1451245600 GRCh38
## ... ... ... ... ...
## [1650] regulatory_overlap DrugCentral DrugCentral:1034:Q9H.. GRCh38
## [1651] regulatory_overlap DrugCentral DrugCentral:2657:Q9H.. GRCh38
## [1652] regulatory_overlap DrugCentral DrugCentral:4113:Q9H.. GRCh38
## [1653] regulatory_overlap DrugCentral DrugCentral:4184:Q9H.. GRCh38
## [1654] regulatory_overlap DrugCentral DrugCentral:5006:Q9H.. GRCh38
## variant_id evidence_score source_database
## <character> <numeric> <character>
## [1] rs12248560 2.0 PharmGKB summary ann..
## [2] CYP2C19*1, CYP2C19*17 6.0 PharmGKB summary ann..
## [3] rs28399504 0.5 PharmGKB summary ann..
## [4] CYP2C19*1, CYP2C19*2.. 1.0 PharmGKB summary ann..
## [5] CYP2C19*1, CYP2C19*2.. 8.0 PharmGKB summary ann..
## ... ... ... ...
## [1650] <NA> NA WOMBAT-PK
## [1651] <NA> NA WOMBAT-PK
## [1652] <NA> NA UNKNOWN
## [1653] <NA> NA CHEMBL
## [1654] <NA> NA SCIENTIFIC LITERATURE
## source_evidence_scope source_database_version gene_product_id
## <character> <character> <character>
## [1] exact_variant <NA> <NA>
## [2] gene_association <NA> <NA>
## [3] exact_variant <NA> <NA>
## [4] gene_association <NA> <NA>
## [5] gene_association <NA> <NA>
## ... ... ... ...
## [1650] gene_association <NA> Q9H244
## [1651] gene_association <NA> Q9H244
## [1652] gene_association <NA> Q9H244
## [1653] gene_association <NA> Q9H244
## [1654] gene_association <NA> Q9H244
## evidence_type source_gene_id source_gene_symbol
## <character> <character> <character>
## [1] <NA> <NA> CYP2C19
## [2] <NA> <NA> CYP2C19
## [3] <NA> <NA> CYP2C19
## [4] <NA> <NA> CYP2C19
## [5] <NA> <NA> CYP2C19
## ... ... ... ...
## [1650] bioactivity <NA> P2RY12
## [1651] mechanism_of_action <NA> P2RY12
## [1652] mechanism_of_action <NA> P2RY12
## [1653] mechanism_of_action <NA> P2RY12
## [1654] mechanism_of_action <NA> P2RY12
## source_genome_build feature_type mapping_id
## <character> <character> <character>
## [1] <NA> promoter record_156:promoter:..
## [2] <NA> promoter record_318:promoter:..
## [3] <NA> promoter record_392:promoter:..
## [4] <NA> promoter record_401:promoter:..
## [5] <NA> promoter record_451:promoter:..
## ... ... ... ...
## [1650] <NA> promoter record_111384:promot..
## [1651] <NA> promoter record_117124:promot..
## [1652] <NA> promoter record_118787:promot..
## [1653] <NA> promoter record_119235:promot..
## [1654] <NA> promoter record_121088:promot..
## -------
## seqinfo: 2 sequences from an unspecified genome; no seqlengthsPromoter mappings receive
evidence_scope = "regulatory_overlap". Gene bodies, coding
exons, UTRs, and introns receive gene_association. Only the
supplied variant coordinate receives exact_variant; merely
mentioning an rsID in a source record is not sufficient.
For TxDb inputs, the available feature modes are:
Promoters use transcript starts and default to 2,000 bases upstream and 500 bases downstream. Distant nearest-gene assignment is not performed.
regions <- GRanges(
seqnames = c("chr10", "chr10", "chr3"),
ranges = IRanges(
start = c(94781000, 94781859, 151383500),
end = c(94782000, 94781859, 151384500)
),
region_id = c("region_1", "region_2", "region_3")
)
annotations <- annotateDrugRegions(regions, drug_ranges)
mcols(annotations)[, c(
"region_id",
"gene_symbol",
"drug_name",
"relationship_category",
"feature_type",
"evidence_scope",
"overlap_bp",
"source"
)]## DataFrame with 1654 rows and 8 columns
## region_id gene_symbol drug_name relationship_category
## <character> <character> <character> <character>
## region_1 region_1 CYP2C19 mephenytoin dosage
## region_1 region_1 CYP2C19 clopidogrel toxicity
## region_1 region_1 CYP2C19 mephenytoin metabolism
## region_1 region_1 CYP2C19 clobazam dosage
## region_1 region_1 CYP2C19 clobazam efficacy
## ... ... ... ... ...
## region_3 region_3 P2RY12 epoprostenol target
## region_3 region_3 P2RY12 ticlopidine target
## region_3 region_3 P2RY12 prasugrel target
## region_3 region_3 P2RY12 ticagrelor target
## region_3 region_3 P2RY12 cangrelor target
## feature_type evidence_scope overlap_bp source
## <character> <character> <integer> <character>
## region_1 gene_body gene_association 1001 ClinPGx
## region_1 gene_body gene_association 1001 ClinPGx
## region_1 gene_body gene_association 1001 ClinPGx
## region_1 gene_body gene_association 1001 ClinPGx
## region_1 gene_body gene_association 1001 ClinPGx
## ... ... ... ... ...
## region_3 promoter regulatory_overlap 1000 DrugCentral
## region_3 promoter regulatory_overlap 1000 DrugCentral
## region_3 promoter regulatory_overlap 1000 DrugCentral
## region_3 promoter regulatory_overlap 1000 DrugCentral
## region_3 promoter regulatory_overlap 1000 DrugCentralBED file paths are imported with rtracklayer, so
zero-based BED coordinates are converted correctly. Data-frame inputs
are explicitly interpreted as one-based closed genomic coordinates.
Rows remain feature- and source-record-specific. Disjoint transcript
pieces within one logical feature mapping are collapsed, and their
overlap is unioned so duplicated isoforms do not inflate
overlap_bp.
## DataFrame with 1381 rows and 12 columns
## region drug relationship n_annotations n_genes overlap_bp
## <character> <character> <character> <integer> <integer> <integer>
## 1 region_1 mephenytoin dosage 2 1 1001
## 2 region_1 clopidogrel toxicity 3 1 1001
## 3 region_1 mephenytoin metabolism 8 1 1001
## 4 region_1 clobazam dosage 1 1 1001
## 5 region_1 clobazam efficacy 1 1 1001
## ... ... ... ... ... ... ...
## 1377 region_3 epoprostenol target 2 1 1001
## 1378 region_3 ticlopidine target 2 1 1001
## 1379 region_3 prasugrel target 2 1 1001
## 1380 region_3 ticagrelor target 2 1 1001
## 1381 region_3 cangrelor target 2 1 1001
## feature_types evidence_scopes evidence_levels
## <character> <character> <character>
## 1 gene_body gene_association 3
## 2 gene_body gene_association 3; 1A
## 3 gene_body gene_association 3
## 4 gene_body gene_association 3
## 5 gene_body gene_association 3
## ... ... ... ...
## 1377 gene_body; promoter gene_association; re.. NA
## 1378 gene_body; promoter gene_association; re.. NA
## 1379 gene_body; promoter gene_association; re.. NA
## 1380 gene_body; promoter gene_association; re.. NA
## 1381 gene_body; promoter gene_association; re.. NA
## strongest_evidence_level has_exact_variant sources
## <character> <logical> <character>
## 1 3 FALSE ClinPGx
## 2 1A FALSE ClinPGx
## 3 3 FALSE ClinPGx
## 4 3 FALSE ClinPGx
## 5 3 FALSE ClinPGx
## ... ... ... ...
## 1377 NA FALSE DrugCentral
## 1378 NA FALSE DrugCentral
## 1379 NA FALSE DrugCentral
## 1380 NA FALSE DrugCentral
## 1381 NA FALSE DrugCentralSummaries include applicable counts, union overlap bases, represented
feature classes, evidence levels, and source provenance. Columns for
dimensions already used in by are omitted.
## R version 4.6.1 (2026-06-24)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 26.04.1 LTS
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so; LAPACK version 3.12.0
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## time zone: Etc/UTC
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats4 stats graphics grDevices utils datasets methods
## [8] base
##
## other attached packages:
## [1] GenomicRanges_1.65.4 Seqinfo_1.3.2 IRanges_2.47.5
## [4] S4Vectors_0.51.10 BiocGenerics_0.59.12 generics_0.1.4
## [7] drugannotR_0.99.0 BiocStyle_2.41.0
##
## loaded via a namespace (and not attached):
## [1] sass_0.4.10 RSQLite_3.53.3 digest_0.6.39
## [4] magrittr_2.0.5 evaluate_1.0.5 fastmap_1.2.0
## [7] blob_1.3.0 jsonlite_2.0.0 GenomeInfoDb_1.49.1
## [10] DBI_1.3.0 BiocManager_1.30.27 httr_1.4.9
## [13] purrr_1.2.2 UCSC.utils_1.9.0 httr2_1.3.0
## [16] jquerylib_0.1.4 cli_3.6.6 rlang_1.3.0
## [19] dbplyr_2.6.0 bit64_4.8.6 withr_3.0.3
## [22] cachem_1.1.0 yaml_2.3.12 otel_0.2.0
## [25] tools_4.6.1 memoise_2.0.1 dplyr_1.2.1
## [28] filelock_1.0.3 curl_8.0.0 buildtools_1.0.0
## [31] vctrs_0.7.3 R6_2.6.1 BiocFileCache_3.3.0
## [34] lifecycle_1.0.5 bit_4.6.0 pkgconfig_2.0.3
## [37] bslib_0.12.0 pillar_1.11.1 glue_1.8.1
## [40] xfun_0.61 tibble_3.3.1 tidyselect_1.2.1
## [43] sys_3.4.3 knitr_1.52 htmltools_0.5.9
## [46] rmarkdown_2.32 maketools_1.3.2 compiler_4.6.1