Queries Ensembl BioMart directly to build up-to-date gene annotation tables ("annotables") using recipes derived from the annotables package. This provides the latest annotations from Ensembl when internet is available, as an alternative to the fixed-version tables stored on Zenodo.
Arguments
- recipes
character vector of recipe names to build, or
NULLto build all available recipes. Usels_annotables()to see which organisms are available (matching the "gene" + "tx2gene" table names). Recipe names include"grch38","grch37","grcm38","bdgp6","galgal5","rnor6","mmul801","wbcel235","cfamiliaris","drerio","sscrofa".- tx2gene
if
TRUE(default), also build transcript-to-gene mapping tables (appended with_tx2genesuffix).- include_synonyms
if
TRUE, also fetchexternal_synonym(gene name aliases) from BioMart and include asynonymcolumn in the output tables. DefaultFALSEfor faster queries.- mirrors
character vector of Ensembl mirror URLs to try in order. The function automatically falls back to the next mirror on failure.
- cache_dir
directory path to cache downloaded tables as
.rdafiles. Set toNULLto skip caching. Default uses the package's data path (customizable viaoptions(IDConverter.datapath = ...)).- verbose
if
TRUE, print progress messages.
Value
a named list of data.frame objects (tibbles). The list names
correspond to recipe names (and _tx2gene variants if tx2gene = TRUE).
Returns invisible(NULL) on total failure.
Details
Requirements: This function requires the Bioconductor package biomaRt. Install it with:
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("biomaRt")Mirror fallback: Ensembl mirrors can be unreliable. The function
tries each mirror in mirrors for each recipe until one succeeds.
If all mirrors fail for a recipe, that recipe is skipped with a warning.
Caching: When cache_dir is set, successfully downloaded tables
are saved as .rda files. Subsequent calls with the same cache_dir
will load from cache instead of re-querying, unless cache_dir = NULL.
See also
load_data() for loading fixed-version tables from Zenodo,
ls_annotables() for listing available tables.
Examples
# \donttest{
# Build a single annotable table
grch38 <- build_annotables("grch38", tx2gene = FALSE)
#> --- Building: grch38 ---
#> Trying mirror: https://www.ensembl.org
#> OK: 91743 rows
#> Cached to: /tmp/Rtmpu9e9wx/grch38.rda
#>
#> Successfully built 1 table(s). Use names() to see available tables.
head(grch38[[1]])
#> # A tibble: 6 × 9
#> ensgene entrez symbol chr start end strand biotype description
#> <chr> <int> <chr> <chr> <int> <int> <int> <chr> <chr>
#> 1 ENSG00000000003 7105 TSPAN6 X 1.01e8 1.01e8 -1 protei… tetraspani…
#> 2 ENSG00000000005 64102 TNMD X 1.01e8 1.01e8 1 protei… tenomodulin
#> 3 ENSG00000000419 8813 DPM1 20 5.09e7 5.10e7 -1 protei… dolichyl-p…
#> 4 ENSG00000000457 57147 SCYL3 1 1.70e8 1.70e8 -1 protei… SCY1 like …
#> 5 ENSG00000000460 55732 FIRRM 1 1.70e8 1.70e8 1 protei… FIGNL1 int…
#> 6 ENSG00000000938 2268 FGR 1 2.76e7 2.76e7 -1 protei… FGR proto-…
# Build all available tables (requires internet + biomaRt)
all_tables <- build_annotables()
#> --- Building: grch38 ---
#> Loading from cache: /tmp/Rtmpu9e9wx/grch38.rda
#> --- Building: grch37 ---
#> Trying mirror: https://www.ensembl.org
#> OK: 91743 rows
#> Cached to: /tmp/Rtmpu9e9wx/grch37.rda
#> --- Building: grcm38 ---
#> Trying mirror: https://www.ensembl.org
#> OK: 78718 rows
#> Cached to: /tmp/Rtmpu9e9wx/grcm38.rda
#> --- Building: rnor6 ---
#> Trying mirror: https://www.ensembl.org
#> OK: 57760 rows
#> Cached to: /tmp/Rtmpu9e9wx/rnor6.rda
#> --- Building: bdgp6 ---
#> Trying mirror: https://www.ensembl.org
#> OK: 28759 rows
#> Cached to: /tmp/Rtmpu9e9wx/bdgp6.rda
#> --- Building: galgal5 ---
#> Trying mirror: https://www.ensembl.org
#> OK: 34332 rows
#> Cached to: /tmp/Rtmpu9e9wx/galgal5.rda
#> --- Building: mmul801 ---
#> Trying mirror: https://www.ensembl.org
#> OK: 37169 rows
#> Cached to: /tmp/Rtmpu9e9wx/mmul801.rda
#> --- Building: wbcel235 ---
#> Trying mirror: https://www.ensembl.org
#> OK: 46926 rows
#> Cached to: /tmp/Rtmpu9e9wx/wbcel235.rda
#> --- Building: cfamiliaris ---
#> Trying mirror: https://www.ensembl.org
#> OK: 34012 rows
#> Cached to: /tmp/Rtmpu9e9wx/cfamiliaris.rda
#> --- Building: drerio ---
#> Trying mirror: https://www.ensembl.org
#> OK: 92137 rows
#> Cached to: /tmp/Rtmpu9e9wx/drerio.rda
#> --- Building: sscrofa ---
#> Trying mirror: https://www.ensembl.org
#> OK: 35819 rows
#> Cached to: /tmp/Rtmpu9e9wx/sscrofa.rda
#> --- Building: grch38_tx2gene ---
#> Trying mirror: https://www.ensembl.org
#> OK: 670670 rows
#> Cached to: /tmp/Rtmpu9e9wx/grch38_tx2gene.rda
#> --- Building: grch37_tx2gene ---
#> Trying mirror: https://www.ensembl.org
#> OK: 670670 rows
#> Cached to: /tmp/Rtmpu9e9wx/grch37_tx2gene.rda
#> --- Building: grcm38_tx2gene ---
#> Trying mirror: https://www.ensembl.org
#> OK: 481956 rows
#> Cached to: /tmp/Rtmpu9e9wx/grcm38_tx2gene.rda
#> --- Building: rnor6_tx2gene ---
#> Trying mirror: https://www.ensembl.org
#> OK: 95472 rows
#> Cached to: /tmp/Rtmpu9e9wx/rnor6_tx2gene.rda
#> --- Building: bdgp6_tx2gene ---
#> Trying mirror: https://www.ensembl.org
#> OK: 41600 rows
#> Cached to: /tmp/Rtmpu9e9wx/bdgp6_tx2gene.rda
#> --- Building: galgal5_tx2gene ---
#> Trying mirror: https://www.ensembl.org
#> OK: 72689 rows
#> Cached to: /tmp/Rtmpu9e9wx/galgal5_tx2gene.rda
#> --- Building: mmul801_tx2gene ---
#> Trying mirror: https://www.ensembl.org
#> OK: 64228 rows
#> Cached to: /tmp/Rtmpu9e9wx/mmul801_tx2gene.rda
#> --- Building: wbcel235_tx2gene ---
#> Trying mirror: https://www.ensembl.org
#> OK: 60000 rows
#> Cached to: /tmp/Rtmpu9e9wx/wbcel235_tx2gene.rda
#> --- Building: cfamiliaris_tx2gene ---
#> Trying mirror: https://www.ensembl.org
#> OK: 55335 rows
#> Cached to: /tmp/Rtmpu9e9wx/cfamiliaris_tx2gene.rda
#> --- Building: drerio_tx2gene ---
#> Trying mirror: https://www.ensembl.org
#> OK: 65905 rows
#> Cached to: /tmp/Rtmpu9e9wx/drerio_tx2gene.rda
#> --- Building: sscrofa_tx2gene ---
#> Trying mirror: https://www.ensembl.org
#> OK: 60440 rows
#> Cached to: /tmp/Rtmpu9e9wx/sscrofa_tx2gene.rda
#>
#> Successfully built 22 table(s). Use names() to see available tables.
names(all_tables)
#> [1] "grch38" "grch37" "grcm38"
#> [4] "rnor6" "bdgp6" "galgal5"
#> [7] "mmul801" "wbcel235" "cfamiliaris"
#> [10] "drerio" "sscrofa" "grch38_tx2gene"
#> [13] "grch37_tx2gene" "grcm38_tx2gene" "rnor6_tx2gene"
#> [16] "bdgp6_tx2gene" "galgal5_tx2gene" "mmul801_tx2gene"
#> [19] "wbcel235_tx2gene" "cfamiliaris_tx2gene" "drerio_tx2gene"
#> [22] "sscrofa_tx2gene"
# }