Gene identifier conversion and annotation is a common and critical task in bioinformatics research. Existing databases and tools use different naming conventions for genes or provide only partial annotations, making it challenging to integrate data from multiple sources. geneslator addresses this problem by providing a unified interface for genome annotation across different databases in several model organisms.
Key Features:
geneslator currently supports 14 different organisms, including Human, Mouse, Rat, Yeast, Worm, Fly, Zebrafish, Arabidopsis and other plant species. In the future releases of the package, the number of supported species will increase to include more model organisms.
if (!require("BiocManager", quietly = TRUE)) {
install.packages("BiocManager")
}
BiocManager::install("geneslator")library(geneslator)geneslator provides species-specific annotation databases for several
organisms. Annotation databases are stored as SQLite files in different
versions of a Zenodo record at https://doi.org/10.5281/zenodo.20448208. Each
release refers to a specific version of the databases. Versions are tagged
as year.month, where year and month denote the year and the month of the
publication of the release (e.g. ‘2026.03’ for March 2026).
Databases are updated on a monthly basis.
Type availableDatabases() to retrieve the list of available databases and
supported species in the most recent release.
# List organisms annotated in geneslator
availableDatabases()
#> Name Organism TaxID
#> 8 org.Athaliana.db Arabidopsis thaliana 3702
#> 10 org.Bnapus.db Brassica napus 3708
#> 9 org.Boleracea.db Brassica oleracea 109376
#> 6 org.Celegans.db Caenorhabditis elegans 6239
#> 4 org.Drerio.db Danio rerio 7955
#> 5 org.Dmelanogaster.db Drosophila melanogaster 7227
#> 1 org.Hsapiens.db Homo sapiens 9606
#> 13 org.Langustifolius.db Lupinus angustifolius 3871
#> 2 org.Mmusculus.db Mus musculus 10090
#> 14 org.Pvulgaris.db Phaseolus vulgaris 3885
#> 3 org.Rnorvegicus.db Rattus norvegicus 10116
#> 7 org.Scerevisiae.db Saccharomyces cerevisiae 559292
#> 11 org.Slycopersicum.db Solanum lycopersicum 4081
#> 12 org.Vvinifera.db Vitis vinifera 29760
#> MD5 Version DOI
#> 8 c27770afa06060c66d2427ac295101dd 2026.07 10.5281/zenodo.21535272
#> 10 464c36dc8dd1ff22c74ac0c632b77e8a 2026.07 10.5281/zenodo.21535272
#> 9 94145a122ce3e81837da82151a207b0d 2026.07 10.5281/zenodo.21535272
#> 6 e615853fd07388202b21d103ef5e24c9 2026.07 10.5281/zenodo.21535272
#> 4 bcbcd13788c41d4b922796a9eff393b8 2026.07 10.5281/zenodo.21535272
#> 5 91802a6c4acf6f82e0009daf4fb47be6 2026.07 10.5281/zenodo.21535272
#> 1 bb344bf0d7cb50f25cb52db9ea7b6e20 2026.07 10.5281/zenodo.21535272
#> 13 a30e70df40e8810785cb39b4bd661556 2026.07 10.5281/zenodo.21535272
#> 2 2c7f1f2a7f5e4d7b1e798bd7b0337d73 2026.07 10.5281/zenodo.21535272
#> 14 098b433b9878b51539ae5d43a0271ebb 2026.07 10.5281/zenodo.21535272
#> 3 deef40b7e1cc1268f8e1e96c0968d919 2026.07 10.5281/zenodo.21535272
#> 7 22b0c6876566f73f8c167bd15734c7ab 2026.07 10.5281/zenodo.21535272
#> 11 a2343c03f91be8ff7ca18c0d87ebc02a 2026.07 10.5281/zenodo.21535272
#> 12 f9d97e4288a1f4dcfb302c3bf87135cd 2026.07 10.5281/zenodo.21535272The parameter release.version can be used to retrieve the list of all
available databases in an older release.
# List organisms annotated in geneslator (release December 2025)
availableDatabases(release.version = "2025.12")
#> Name Organism TaxID
#> 1 org.Athaliana.db Arabidopsis thaliana 3702
#> 6 org.Celegans.db Caenorhabditis elegans 6239
#> 8 org.Drerio.db Danio rerio 7955
#> 2 org.Dmelanogaster.db Drosophila melanogaster 7227
#> 3 org.Hsapiens.db Homo sapiens 9606
#> 4 org.Mmusculus.db Mus musculus 10090
#> 5 org.Rnorvegicus.db Rattus norvegicus 10116
#> 7 org.Scerevisiae.db Saccharomyces cerevisiae 559292
#> MD5 Version DOI
#> 1 a292153eee87600c5d8c27977fe7ea45 2025.12 10.5281/zenodo.20448209
#> 6 fb4f03098e379712c17196a1f2b6c6a4 2025.12 10.5281/zenodo.20448209
#> 8 e292dcb2cca5c038d9c369b31ca16d8c 2025.12 10.5281/zenodo.20448209
#> 2 06031138af0a7e44af7d9f938f8f4239 2025.12 10.5281/zenodo.20448209
#> 3 6b6ffd437724b029e3ec5f24ab866d97 2025.12 10.5281/zenodo.20448209
#> 4 1f5af73caf5e89f65e7bcf31669f62d0 2025.12 10.5281/zenodo.20448209
#> 5 7cb6dbed9441b0b142032a5206b66126 2025.12 10.5281/zenodo.20448209
#> 7 7b36f0be0eecce6e12bf05f32d5d8779 2025.12 10.5281/zenodo.20448209A complete list of all available release versions can be obtained with
availableVersions().
# List available versions of geneslator annotation databases
availableVersions()
#> [1] "2025.12" "2026.03" "2026.04" "2026.05" "2026.06" "2026.07"To query a database for a specific organism org, you first need to import
it, by using the GeneslatorDb function. org can be either the scientific
name of the organism (e.g. “Homo sapiens”) or its Taxonomy ID (e.g. “10090”
for Mouse). The function creates a new GeneslatorDb object for the
requested database, which is then exported to the global environment of the
user as a variable having the same name of the SQLite annotation database
(e.g. org.Hsapiens.db for Human, org.Mmusculus.db for Mouse).
# Import human annotation db (after downloading it from remote repository)
GeneslatorDb("Homo sapiens")
# Info about the imported human annotation database object
org.Hsapiens.db
#> GeneslatorDb object
#> Organism: Homo sapiens
#> Columns: ALIAS, ENSEMBL, ENSEMBLOLD, ENTREZID, ENTREZIDOLD, GENENAME, GENETYPE, GID, GO, GOEVIDENCE, GONAME, GOTYPE, HGNC, KEGGPATH, KEGGPATHNAME, LOCUS, ORTHOFLY, ORTHOMOUSE, ORTHORAT, ORTHOWORM, ORTHOYEAST, ORTHOZEBRAFISH, REACTOMEPATH, REACTOMEPATHNAME, SYMBOL, UNIPROT, WIKIPATH, WIKIPATHNAME
# Import mouse annotation database using its Taxonomy ID
GeneslatorDb("10090")
# Info about the imported human annotation database object
org.Mmusculus.db
#> GeneslatorDb object
#> Organism: Mus musculus
#> Columns: ALIAS, ENSEMBL, ENSEMBLOLD, ENTREZID, ENTREZIDOLD, GENENAME, GENETYPE, GID, GO, GOEVIDENCE, GONAME, GOTYPE, KEGGPATH, KEGGPATHNAME, MGI, ORTHOFLY, ORTHOHUMAN, ORTHORAT, ORTHOWORM, ORTHOYEAST, ORTHOZEBRAFISH, REACTOMEPATH, REACTOMEPATHNAME, SYMBOL, UNIPROT, WIKIPATH, WIKIPATHNAMEWhen called for the first time on a specific organism, GeneslatorDb function
downloads the annotation database from the remote repository, stores a local
copy into your R cache folder and finally imports the database. Future calls
to GeneslatorDb function will simply import the database from your cache,
unless a new version of the database is present in the remote repository.
In the latter case, you will be notified about that and you will be able to
choose whether or not updating your local copy in the R cache, before importing
the database.
# Import human db again. Now cache data will be used to import db
GeneslatorDb("Homo sapiens")By default, GeneslatorDb queries the latest release. To retrieve an older
version of the database, you can set the release.version parameter to the
desired release version. Again, a local copy of the database (distinct from the
latest release) will be stored into your R cache folder, so that future calls
to the same database will simply import it from your cache.
# Import yeast annotation db from release 2025.12 (December 2025)
GeneslatorDb("Saccharomyces cerevisiae", release.version = "2025.12")
# Info about the imported human annotation database object
org.Scerevisiae.db
#> GeneslatorDb object
#> Organism: Saccharomyces cerevisiae
#> Columns: ALIAS, ENSEMBL, ENSEMBLOLD, ENTREZID, ENTREZIDOLD, GENENAME, GENETYPE, GID, GO, GOEVIDENCE, GONAME, GOTYPE, KEGGPATH, KEGGPATHNAME, LOCUS, ORTHOFLY, ORTHOHUMAN, ORTHOMOUSE, ORTHORAT, ORTHOWORM, ORTHOZEBRAFISH, REACTOMEPATH, REACTOMEPATHNAME, SGD, SYMBOL, UNIPROT, WIKIPATH, WIKIPATHNAMEAnnotation databases are internally represented as collections of R dataframes that can be queried through functions that map a set of values of an input column (the key) of a dataframe to the corresponding values of one or more output columns of the same or a different dataframe.
Function keytypes() lists all columns that can be used as keys.
# Get all columns that can be used as keys in mouse annotation db
geneslator::keytypes(org.Mmusculus.db)
#> [1] "ALIAS" "ENSEMBL" "ENSEMBLOLD" "ENTREZID"
#> [5] "ENTREZIDOLD" "GENENAME" "GENETYPE" "GO"
#> [9] "KEGGPATH" "MGI" "ORTHOFLY" "ORTHOHUMAN"
#> [13] "ORTHORAT" "ORTHOWORM" "ORTHOYEAST" "ORTHOZEBRAFISH"
#> [17] "REACTOMEPATH" "SYMBOL" "UNIPROT" "WIKIPATH"Similarly, function columns() lists all possible output columns.
# Get all available types of output values in mouse annotation db
geneslator::columns(org.Mmusculus.db)
#> [1] "ALIAS" "ENSEMBL" "ENSEMBLOLD" "ENTREZID"
#> [5] "ENTREZIDOLD" "GENENAME" "GENETYPE" "GO"
#> [9] "GOEVIDENCE" "GONAME" "GOTYPE" "KEGGPATH"
#> [13] "KEGGPATHNAME" "MGI" "ORTHOFLY" "ORTHOHUMAN"
#> [17] "ORTHORAT" "ORTHOWORM" "ORTHOYEAST" "ORTHOZEBRAFISH"
#> [21] "REACTOMEPATH" "REACTOMEPATHNAME" "SYMBOL" "UNIPROT"
#> [25] "WIKIPATH" "WIKIPATHNAME"Note that the output of the two functions is different, because only identifier
columns can be used as keys, while any column can be an output column. Type
help("columns","geneslator") to see the complete list of columns available in
the annotation databases of geneslator, together with their description.
Function keys() is used to retrieve all values of a column in an annotation
database.
# Get the first 10 Entrez IDs in mouse annotation db
head(geneslator::keys(org.Mmusculus.db, keytype = "ENTREZID"), 10)
#> [1] "100008564" "100008567" "100009600" "100009609" "100009614" "100009664"
#> [7] "100009698" "100010" "100012" "100014"Columns of the annotation databases can be queried using properly re-defined
versions of the well-known query functions select() and mapIds() of
AnnotationDbi R package.
The select() function allows you to query an input key column of the
annotation database (keytype argument) and retrieve related information
across one or more other columns (columns argument).
The output of select() is a dataframe with all columns specified by keytype
and columns arguments and one row for each mapping found between input and
output values.
# Map NCBI Gene IDs to gene symbols and Ensembl IDs in Human
genes <- c("1", "2", "9")
result <- geneslator::select(org.Hsapiens.db,
keys = genes,
columns = c("SYMBOL", "ENSEMBL"), keytype = "ENTREZID"
)
result
#> ENTREZID SYMBOL ENSEMBL
#> 1 1 A1BG ENSG00000121410
#> 2 2 A2M ENSG00000175899
#> 3 9 NAT1 ENSG00000171428Unlike select(), mapIds() maps an input key column (argument keytype) to
a single output column (argument column).
# Convert gene symbols to ENTREZ IDs (first match only)
genes <- c("TP53", "BRCA1", "EGFR")
entrez_ids <- geneslator::mapIds(org.Hsapiens.db,
keys = genes,
column = "ENTREZID", keytype = "SYMBOL"
)
entrez_ids
#> TP53 BRCA1 EGFR
#> "7157" "672" "1956"By default, the return type is a named vector, where each value is the first
mapping found (if any) for a given key, even if multiple output values map to
that key. However, this behaviour can be changed through the multiVals
parameter, which also controls the shape of the output result. For example,
multiVals="list" produces a list object with all matches found for each input.
# Get all possible mappings as a list
entrez_list <- geneslator::mapIds(org.Hsapiens.db,
keys = genes,
column = "ENTREZID", keytype = "SYMBOL", multiVals = "list"
)
entrez_list
#> $TP53
#> [1] "7157"
#>
#> $BRCA1
#> [1] "672"
#>
#> $EGFR
#> [1] "1956"In select() and mapIds() functions, by default, queries of annotation
databases involving gene symbols are performed by first looking at column
“SYMBOL” and, if no mapping is found using “SYMBOL”, the query is performed
using the “ALIAS” column. This is helpful when users unknowingly start from a
list of names that is actually a mix of official gene symbols and aliases.
This behaviour of select() and mapIds() can be controlled through the
boolean parameter search.aliases, whose default value is TRUE.
In the following example, “BRCAI” is actually an alias of BRCA1 gene, while
“PTEN” is the official symbol of the PTEN gene. When mapping these two keys
(treated as SYMBOL) to ENTREZID by using select(), BRCAI is correctly viewed
as an alias of BRCA1 gene and mapped to the NCBI gene id of BRCA1.
# Map gene symbols to their NCBI gene ids, querying also the ALIAS column
# if needed
result <- geneslator::select(org.Hsapiens.db,
keys = c("BRCAI", "PTEN"),
columns = "ENTREZID", keytype = "SYMBOL"
)
result
#> SYMBOL ENTREZID
#> 1 BRCAI 672
#> 2 PTEN 5728Whenever ALIAS column is used in place of SYMBOL column (as in this example),
a warning message is sent to the user. If we repeat the same query with
search.aliases=FALSE, select() is unable to map BRCAI to the correct
NCBI gene id.
# Map gene symbols to their NCBI gene ids, querying only the SYMBOL column
result <- geneslator::select(org.Hsapiens.db,
keys = c("BRCAI", "PTEN"),
columns = "ENTREZID", keytype = "SYMBOL", search.aliases = FALSE
)
result
#> SYMBOL ENTREZID
#> 1 BRCAI <NA>
#> 2 PTEN 5728Gene identifiers and symbols can change over time or become deprecated, as a
result of periodic updates of databases such as NCBI or Ensembl. This could be
troublesome in annotation tasks, especially when user starts from an old set of
identifiers or symbols. To overcome this, annotation databases in
geneslator contain columns “ENTREZIDOLD” and “ENSEMBLOLD”, which collect
old gene identifiers of NCBI Gene and Ensembl databases.
By default, these columns are queried by select() and mapIds() methods
whenever a gene cannot be annotated using current identifiers. This behaviour
can be controlled through the boolean parameter search.archives, whose
default value is TRUE.
For example, in the following query key “3” corresponds to the old NCBI Gene
identifier of gene “A2MP1”. By using archived data, select() is able to
correctly map NCBI Gene ID “3” to gene symbol “A2MP1”.
# Map NCBI gene id 3 to gene symbol, using both current and old identifiers
result <- geneslator::select(org.Hsapiens.db,
keys = "3", columns = "SYMBOL",
keytype = "ENTREZID"
)
result
#> ENTREZID SYMBOL
#> 1 3 PZP2PWhenever archived identifiers are used to solve a query (as in this example),
a warning message is sent to the user. If we set search.archives=FALSE,
select() is unable to map the identifier to the correct symbol.
# Map NCBI gene id 3 to gene symbol, using only current identifiers
result <- geneslator::select(org.Hsapiens.db,
keys = "3", columns = "SYMBOL",
keytype = "ENTREZID", search.archives = FALSE
)
result
#> ENTREZID SYMBOL
#> 1 3 NAIn queries involving orthologs mapping, by default, select() returns all
possible ortholog mappings. This behavior is controlled by parameter
orthologs.mapping, whose default value is “multiple”.
# Get orthologs of yeast genes CHC1 and NMA2 in worm and fly
result <- geneslator::select(org.Hsapiens.db,
keys = c("CHC1", "SCAMP5"),
columns = c("ORTHOWORM", "ORTHOFLY"), keytype = "SYMBOL"
)
result
#> SYMBOL ORTHOWORM ORTHOFLY
#> 1 CHC1 ran-3 CG33288
#> 2 CHC1 ran-3 CG7420
#> 3 CHC1 ran-3 Rcc1
#> 4 SCAMP5 scm-1 ScampTo get only the first ortholog, set orthologs.mapping="single":
result <- geneslator::select(org.Hsapiens.db,
keys = c("CHC1", "SCAMP5"),
columns = c("ORTHOWORM", "ORTHOFLY"), keytype = "SYMBOL",
orthologs.mapping = "single"
)
result
#> SYMBOL ORTHOWORM ORTHOFLY
#> 1 CHC1 ran-3 CG33288
#> 2 SCAMP5 scm-1 ScampFor mapIds() function, the option orthologs.mapping is absent, because the
number of mapped orthologs can be directly controlled through parameter
multiVals.
sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.4 LTS
#>
#> Matrix products: default
#> BLAS: /home/biocbuild/bbs-3.24-bioc/R/lib/libRblas.so
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0 LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_GB LC_COLLATE=C
#> [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: America/New_York
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats4 stats graphics grDevices utils datasets methods
#> [8] base
#>
#> other attached packages:
#> [1] AnnotationDbi_1.75.2 IRanges_2.47.2 S4Vectors_0.51.6
#> [4] Biobase_2.73.2 BiocGenerics_0.59.12 generics_0.1.4
#> [7] geneslator_0.99.10 BiocStyle_2.41.0
#>
#> loaded via a namespace (and not attached):
#> [1] utf8_1.2.6 sass_0.4.10 xml2_1.6.0
#> [4] zen4R_0.10.6 RSQLite_3.53.3 digest_0.6.39
#> [7] magrittr_2.0.5 evaluate_1.0.5 bookdown_0.47
#> [10] fastmap_1.2.0 blob_1.3.0 plyr_1.8.9
#> [13] jsonlite_2.0.0 DBI_1.3.0 BiocManager_1.30.27
#> [16] httr_1.4.8 purrr_1.2.2 XML_3.99-0.23
#> [19] Biostrings_2.81.6 httr2_1.3.0 jquerylib_0.1.4
#> [22] cli_3.6.6 rlang_1.3.0 crayon_1.5.3
#> [25] dbplyr_2.6.0 XVector_0.53.0 bit64_4.8.2
#> [28] withr_3.0.3 cachem_1.1.0 yaml_2.3.12
#> [31] otel_0.2.0 BiocBaseUtils_1.15.1 tools_4.6.1
#> [34] memoise_2.0.1 dplyr_1.2.1 filelock_1.0.3
#> [37] curl_7.1.0 vctrs_0.7.3 R6_2.6.1
#> [40] png_0.1-9 lifecycle_1.0.5 BiocFileCache_3.3.0
#> [43] KEGGREST_1.53.6 Seqinfo_1.3.0 bit_4.6.0
#> [46] pkgconfig_2.0.3 bslib_0.12.0 pillar_1.11.1
#> [49] Rcpp_1.1.2 glue_1.8.1 xfun_0.60
#> [52] tibble_3.3.1 tidyselect_1.2.1 keyring_1.4.1
#> [55] knitr_1.51 htmltools_0.5.9 rmarkdown_2.31
#> [58] compiler_4.6.1Micale G, Cavallaro G, Privitera GF (2026). geneslator: A Comprehensive Gene Identifier Conversion Tool. R package version 0.99.3.
Pages H, Carlson M, Falcon S, Li N (2024). AnnotationDbi: Manipulation of SQLite-based annotations in Bioconductor. R package.
NCBI Gene: https://www.ncbi.nlm.nih.gov/gene
Ensembl: https://www.ensembl.org
UniProt: https://www.uniprot.org
Gene Ontology: http://geneontology.org
KEGG: https://www.kegg.jp
Reactome: https://reactome.org
WikiPathways: https://www.wikipathways.org
Alliance of Genome Resources: https://www.alliancegenome.org