Add hosts argument to useEnsemblGenomes. #93

R/ensembl.R

@@ -347,12 +347,17 @@ useEnsembl <- function(biomart, dataset, host,
 
 ##############################################
 
-listEnsemblGenomes <- function(includeHosts = FALSE){
+listEnsemblGenomes <- function(includeHosts = FALSE, host = NULL){
 
-  hosts <- c("https://protists.ensembl.org/",
-             "https://fungi.ensembl.org/",
-             "https://metazoa.ensembl.org/",
-             "https://plants.ensembl.org/")
+  ## use the default websites unless an alternative is provided
+  if(is.null(host)) {
+    hosts <- c("https://protists.ensembl.org/",
+               "https://fungi.ensembl.org/",
+               "https://metazoa.ensembl.org/",
+               "https://plants.ensembl.org/")
+  } else {
+    hosts <- host
+  }
 
   http_config <- .getEnsemblSSL()
 
@@ -369,15 +374,15 @@ listEnsemblGenomes <- function(includeHosts = FALSE){
   return(marts)
 }
 
-useEnsemblGenomes <- function(biomart, dataset) {
+useEnsemblGenomes <- function(biomart, dataset, host = NULL) {
 
   if(missing(biomart)) {
     stop("You must provide the argument 'biomart'\n",
          "Available Ensembl Genomes Marts can be viewed with ",
          "the function listEnsemblGenomes()")
   }
 
-  marts <- listEnsemblGenomes(includeHosts = TRUE)
+  marts <- listEnsemblGenomes(includeHosts = TRUE, host = host)
   if(!biomart %in% marts$biomart) {
     stop(biomart, " is not in the list of available Marts'\n",
          "Available Ensembl Genomes Marts can be viewed with ",

man/listEnsembl.Rd

@@ -8,7 +8,7 @@ function.}
 \usage{
     listEnsembl(mart = NULL, version = NULL, 
                 GRCh = NULL, mirror = NULL, verbose = FALSE)
-    listEnsemblGenomes(includeHosts = FALSE)
+    listEnsemblGenomes(includeHosts = FALSE, host = NULL)
 }
 \arguments{
 \item{mart}{mart object created with the useEnsembl function.  This is optional, as you usually use \code{\link{listMarts}} to see which marts there are to connect to.}
@@ -18,13 +18,20 @@ function.}
 \item{verbose}{Give detailed output of what the method is doing, for debugging purposes}
 \item{includeHosts}{If this option is set to \code{TRUE} a more detailed 
 output is produced, including the URL used to access the corresponding mart.}
+\item{host}{Host to connect to. Use this argument to specify and archive site for \code{listEnsemblGenomes} to work with.}
 }
 
 \author{Steffen Durinck, Mike L. Smith} 
 
 \examples{
 if(interactive()){
 listEnsembl()
+
+## list the default Ensembl Genomes marts
+listEnsemblGenomes()
+
+## list only the marts available in the Ensmbl Plans 56 archive
+listEnsemblGenomes(host = "https://eg56-plants.ensembl.org/")
 }
 }
 \keyword{methods}

man/useEnsembl.Rd

@@ -15,13 +15,13 @@ on the selected Mart object.}
 \usage{
 useEnsembl(biomart, dataset, host, version = NULL, 
             GRCh = NULL, mirror = NULL, verbose = FALSE)
-useEnsemblGenomes(biomart, dataset)
+useEnsemblGenomes(biomart, dataset, host = NULL)
 }
 
 \arguments{
 \item{biomart}{BioMart database name you want to connect to. Possible database names can be retrieved with the function \code{\link{listEnsembl}}}
 \item{dataset}{Dataset you want to use.  To see the different datasets available within a biomaRt you can e.g. do:  mart = useEnsembl('genes'), followed by listDatasets(mart).}
-\item{host}{Host to connect to.  Only needs to be specified if different from www.ensembl.org}
+\item{host}{Host to connect to.  Only needs to be specified if different from www.ensembl.org.  For \code{useEnsemblGenomes} this argument can be used to specify an archive site.}
 \item{version}{Ensembl version to connect to when wanting to connect to an archived Ensembl version}
 \item{GRCh}{GRCh version to connect to if not the current GRCh38, currently this can only be 37}
 \item{mirror}{Specify an Ensembl mirror to connect to.  The valid options here are 'www', 'useast', 'asia'.  If no mirror is specified the primary site at www.ensembl.org will be used.  Mirrors are not available for the Ensembl Genomes databases.}
@@ -48,6 +48,15 @@ mart <- useEnsembl("ensembl")
 
 ## using the US West mirror
 us_mart <- useEnsembl(biomart = "ensembl", mirror = "useast")
+
+## using the arabidopsis thaliana genes dataset in Ensembl Plants
+plants_mart <- useEnsemblGenomes(biomart = "plants_mart",
+                                 dataset = "athaliana_eg_gene")
+
+## using the cucumis melo genes dataset in the Ensembl Plants 56 archive
+plants_mart <- useEnsemblGenomes(biomart = "plants_mart",
+                                 dataset = "cmelo_eg_gene",
+                                 host = "https://eg56-plants.ensembl.org/")
 }
 }
 \keyword{methods}

tests/testthat/test_ensemblGenomes.R

@@ -7,7 +7,7 @@ test_that("Error handling works", {
 
     mockery::stub(useEnsemblGenomes,
          'listEnsemblGenomes',
-         function(includeHosts) {
+         function(includeHosts, host) {
              data.frame(
                biomart = c("protists_mart", "fungi_mart"),
                version = c("Ensembl Protists Genes 48", "Ensembl Fungi Genes 48")