biomaRt/DESCRIPTION0000644000175400017540000000261613001246365014710 0ustar00biocbuildbiocbuildPackage: biomaRt Version: 2.30.0 Title: Interface to BioMart databases (e.g. Ensembl, COSMIC, Wormbase and Gramene) Author: Steffen Durinck , Wolfgang Huber Contributors: Sean Davis , Francois Pepin, Vince S. Buffalo, Mike Smith Maintainer: Steffen Durinck Depends: methods Imports: utils, XML, RCurl, AnnotationDbi Suggests: annotate, BiocStyle, knitr, rmarkdown VignetteBuilder: knitr biocViews: Annotation Description: In recent years a wealth of biological data has become available in public data repositories. Easy access to these valuable data resources and firm integration with data analysis is needed for comprehensive bioinformatics data analysis. biomaRt provides an interface to a growing collection of databases implementing the BioMart software suite (http://www.biomart.org). The package enables retrieval of large amounts of data in a uniform way without the need to know the underlying database schemas or write complex SQL queries. Examples of BioMart databases are Ensembl, COSMIC, Uniprot, HGNC, Gramene, Wormbase and dbSNP mapped to Ensembl. These major databases give biomaRt users direct access to a diverse set of data and enable a wide range of powerful online queries from gene annotation to database mining. License: Artistic-2.0 LazyLoad: yes NeedsCompilation: no Packaged: 2016-10-17 22:13:09 UTC; biocbuild biomaRt/NAMESPACE0000644000175400017540000000106313001231112014374 0ustar00biocbuildbiocbuildimport(methods) import(RCurl,XML) importFrom(utils, edit, head, read.table) importFrom(AnnotationDbi, keys, columns, keytypes, select) #for some reason RCurl needs to have findHTTPHeaderEncoding exported - #remove it from the exports if this ever gets fixed export(listMarts, getGene, getSequence, exportFASTA, useMart, listDatasets, useDataset, listEnsembl, useEnsembl, listAttributes, listFilters, getBM, getXML,getLDS, attributePages, filterOptions,filterType, getBMlist, NP2009code, keys, columns, keytypes, select) exportClasses(Mart) exportMethods("show") biomaRt/NEWS0000644000175400017540000000023313001231112013652 0ustar00biocbuildbiocbuildCHANGES IN VERSION 2.30.0 ------------------------- SIGNIFICANT USER-LEVEL CHANGES o Updated vignette to use BiocStyle and execute most code chunks. biomaRt/R/0000755000175400017540000000000013001231112013356 5ustar00biocbuildbiocbuildbiomaRt/R/biomaRt.R0000644000175400017540000012514713001231112015110 0ustar00biocbuildbiocbuild ########################## #biomaRt source code # ########################## # # #Licence: Artistic # #Author: Steffen Durinck # ########################## ############### #messageToUser# ############### messageToUser <- function(message){ if(interactive()){ cat(message) } } ############################################################## #martCheck # # # #This function checks if there is a valid Mart object, # #if a dataset is selected and # #if the correct BioMart database has been selected (optional)# ############################################################## martCheck = function(mart, biomart = NULL){ if( missing( mart ) || class( mart ) != 'Mart'){ stop("You must provide a valid Mart object. To create a Mart object use the function: useMart. Check ?useMart for more information.") } if(!is.null(biomart)){ # martcheck = strsplit(martBM(mart),"_", fixed = TRUE, useBytes = TRUE)[[1]][1] martcheck = martBM(mart) bmok = FALSE for(k in 1:length(biomart)){ if(martcheck[1] == biomart[k]){ bmok = TRUE } } if(!bmok){ stop(paste("This function only works when used with the ",biomart," BioMart.",sep="")) } } if(martDataset(mart)==""){ stop("No dataset selected, please select a dataset first. You can see the available datasets by using the listDatasets function see ?listDatasets for more information. Then you should create the Mart object by using the useMart function. See ?useMart for more information"); } } checkWrapperArgs = function(id, type, mart){ if(missing(type))stop("Specify the type of identifier you are using, see ?getGene for details. Valid values for the type argument can be found with the listFilters function.") if(!type %in% listFilters(mart)[,1])stop(paste("Invalid identifier type:",type," see ?getGene for details. Use the listFilters function to get the valid value for the type argument.", sep="")) if(missing(id))stop("No identifiers specified. Use the id argument to specify a vector of identifiers for which you want to retrieve the annotation.") } ####################################################### #listMarts: # #list all available BioMart databases by default # #listMarts will check the central service to see which# #BioMart databases are present # ####################################################### bmRequest <- function(request, ssl.verifypeer = TRUE, verbose = FALSE){ if(verbose) writeLines(paste("Attempting web service request:\n",request, sep="")) result = tryCatch(getURL(request, ssl.verifypeer = ssl.verifypeer,followlocation = TRUE), error = function(e){ cat("Request to BioMart web service failed. Verify if you are still connected to the internet. Alternatively the BioMart web service is temporarily down. Check http://www.biomart.org and verify if this website is available.\n")}) return(result) } listMarts <- function( mart = NULL, host="www.ensembl.org", path="/biomart/martservice", port=80,includeHosts = FALSE, archive = FALSE, ssl.verifypeer = TRUE, verbose = FALSE){ request = NULL if(is.null(mart)){ if(archive){ request = paste("http://",host,":",port,path,"?type=registry_archive&requestid=biomaRt", sep="") } else{ request = paste("http://",host,":",port,path,"?type=registry&requestid=biomaRt", sep="") } } else{ if(class(mart) == 'Mart'){ request = paste(martHost(mart),"?type=registry&requestid=biomaRt", sep="") } else{ warning(paste(mart,"object needs to be of class Mart created with the useMart function. If you don't have a Mart object yet, use listMarts without arguments or only specify the host argument",sep=" ")) } } registry = bmRequest(request = request, ssl.verifypeer = ssl.verifypeer, verbose = verbose) registry = xmlTreeParse(registry, asText=TRUE) registry = registry$doc$children[[1]] marts = list(biomart = NULL, version = NULL, host = NULL, path = NULL, database = NULL) index = 1 if(host != "www.biomart.org" || archive){ for(i in seq(len=xmlSize(registry))){ if(xmlName(registry[[i]])=="MartURLLocation"){ if(xmlGetAttr(registry[[i]],"visible") == 1){ if(!is.null(xmlGetAttr(registry[[i]],"name"))) marts$biomart[index] = as.character(xmlGetAttr(registry[[i]],"name")) if(!is.null(xmlGetAttr(registry[[i]],"database"))) marts$database[index] = as.character(xmlGetAttr(registry[[i]],"database")) if(!is.null(xmlGetAttr(registry[[i]],"displayName"))) marts$version[index] = as.character(xmlGetAttr(registry[[i]],"displayName")) if(!is.null(xmlGetAttr(registry[[i]],"host"))) marts$host[index] = as.character(xmlGetAttr(registry[[i]],"host")) if(!is.null(xmlGetAttr(registry[[i]],"path"))) marts$path[index] = as.character(xmlGetAttr(registry[[i]],"path")) if(!is.null(xmlGetAttr(registry[[i]],"port"))) marts$port[index] = as.character(xmlGetAttr(registry[[i]],"port")) if(!is.null(xmlGetAttr(registry[[i]],"serverVirtualSchema"))){ marts$vschema[index] = as.character(xmlGetAttr(registry[[i]],"serverVirtualSchema")) } index=index+1 } } } } else{ for(i in seq(len=xmlSize(registry))){ if(xmlName(registry[[i]])=="MartURLLocation"){ if(xmlGetAttr(registry[[i]],"visible") == 1){ if(!is.null(xmlGetAttr(registry[[i]],"name"))) marts$biomart[index] = xmlGetAttr(registry[[i]],"name") if(!is.null(xmlGetAttr(registry[[i]],"database"))) marts$database[index] = xmlGetAttr(registry[[i]],"database") if(!is.null(xmlGetAttr(registry[[i]],"displayName"))) marts$version[index] = xmlGetAttr(registry[[i]],"displayName") marts$host[index] = host marts$path[index] = path marts$port[index] = 80 if(!is.null(xmlGetAttr(registry[[i]],"serverVirtualSchema"))){ marts$vschema[index] = xmlGetAttr(registry[[i]],"serverVirtualSchema") } index=index+1 } } } } if(includeHosts){ return(marts) } else{ if(archive){ ret = data.frame(biomart = as.character(marts$database),version = as.character(marts$version), stringsAsFactors=FALSE) } else{ ret = data.frame(biomart = as.character(marts$biomart),version = as.character(marts$version), stringsAsFactors=FALSE) } return(ret) } } ################################# # # # # # # Generic BioMart functions # # # # # # ################################# useMart <- function(biomart, dataset, host = "www.ensembl.org", path = "/biomart/martservice", port = 80, archive = FALSE, ssl.verifypeer = TRUE, version, verbose = FALSE){ if(missing(biomart) && missing(version)) stop("No biomart databases specified. Specify a biomart database to use using the biomart or version argument") if(!missing(biomart)){ if(!(is.character(biomart))) stop("biomart argument is no string. The biomart argument should be a single character string") } if(biomart == "ensembl" & (host == "www.ensembl.org" | host == "uswest.ensembl.org")){ biomart = "ENSEMBL_MART_ENSEMBL" } reqHost = host marts=NULL marts=listMarts(host=host, path=path, port=port, includeHosts = TRUE, archive = archive, ssl.verifypeer = ssl.verifypeer) mindex = NA if(!missing(biomart)){ mindex=match(biomart,marts$biomart) } if(!missing(version)){ mindex=match(version,marts$version) } if(is.na(mindex) || archive){ mindex=match(biomart,marts$database) } if(is.na(mindex)) stop("Incorrect BioMart name, use the listMarts function to see which BioMart databases are available") if(is.na(marts$path[mindex]) || is.na(marts$vschema[mindex]) || is.na(marts$host[mindex]) || is.na(marts$port[mindex]) || is.na(marts$path[mindex])) stop("The selected biomart databases is not available due to error in the BioMart central registry, please report so the BioMart registry file can be fixed.") if(marts$path[mindex]=="") marts$path[mindex]="/biomart/martservice" #temporary to catch bugs in registry if(archive) biomart = marts$biomart[mindex] if(!missing(version)) biomart = marts$biomart[mindex] biomart = sub(" ","%20",biomart, fixed = TRUE, useBytes = TRUE) mart <- new("Mart", biomart = biomart,vschema = marts$vschema[mindex], host = paste("http://",marts$host[mindex],":",marts$port[mindex],marts$path[mindex],sep=""), archive = archive) if(length(grep("archive",martHost(mart)) > 0)){ if(length(grep(reqHost,martHost(mart))) == 0){ writeLines(paste("Note: requested host was redirected from ", reqHost, " to " ,martHost(mart),sep="")) writeLines("When using archived Ensembl versions this sometimes can result in connecting to a newer version than the intended Ensembl version") writeLines("Check your ensembl version using listMarts(mart)") } } BioMartVersion=bmVersion(mart, verbose=verbose) if(martHost(mart) =="http://www.biomart.org:80/biomart/martservice"){ if(verbose) writeLines("Using Central Repository at www.biomart.org"); martVSchema(mart) <- 'default' #Assume central service query uses default vSchema } if(verbose){ writeLines(paste("BioMartServer running BioMart version:",BioMartVersion,sep=" ")) writeLines(paste("Mart virtual schema:",martVSchema(mart),sep=" ")) if(length(grep(reqHost,martHost(mart))) == 0){ writeLines(paste("Requested host was redirected from ", reqHost, " to " ,martHost(mart),sep="")) } writeLines(paste("Mart host:",martHost(mart),sep=" ")) } if(!missing(dataset)){ mart = useDataset(mart = mart, dataset=dataset, verbose = verbose) } return(mart) } listDatasets <- function(mart, verbose = FALSE) { if(missing(mart) || !is(mart, 'Mart')) stop("No Mart object given or object not of class 'Mart'") request = paste(martHost(mart),"?type=datasets&requestid=biomaRt&mart=",martBM(mart),sep="") bmResult = bmRequest(request = request, verbose = verbose) con = textConnection(bmResult) txt = scan(con, sep="\t", blank.lines.skip=TRUE, what="character", quiet=TRUE) #txt = tryCatch(scan(request, sep="\t", blank.lines.skip=TRUE, what="character", quiet=TRUE), error = function(e){stop("Request to BioMart web service failed. Verify if you are still connected to the internet. Alternatively the BioMart web service is temporarily down.")}) close(con) ## select visible ("1") table sets i = intersect(which(txt=="TableSet"), which(txt=="1")-3L) res = data.frame(dataset = I(txt[i+1L]), description = I(txt[i+2L]), version = I(txt[i+4L])) return(res) } ## Check version of BioMart service bmVersion <- function(mart, verbose=FALSE){ request = "" request = paste(martHost(mart),"?type=version","&requestid=biomaRt&mart=",martBM(mart),sep="") BioMartVersion = bmRequest(request = request, verbose = verbose) bmv = "" if(BioMartVersion == "\n" | BioMartVersion == ""){ bmv = NA if(verbose) warning(paste("BioMart version is not available from BioMart server:",request,sep="\n")) } else{ con = textConnection(BioMartVersion) bmVersionParsed = read.table(con, sep="\t", header=FALSE, quote = "", comment.char = "", as.is=TRUE) close(con) if(verbose) print(bmVersionParsed) if(dim(bmVersionParsed)[2] >=1){ bmv=bmVersionParsed[1,1] } } return(bmv) } ## Retrieve attributes and filters from web service bmAttrFilt <- function(type, mart, verbose=FALSE){ request = "" request = paste(martHost(mart),"?type=",type,"&dataset=",martDataset(mart),"&requestid=biomaRt&mart=",martBM(mart),"&virtualSchema=",martVSchema(mart),sep="") attrfilt = bmRequest(request = request, verbose = verbose) con = textConnection(attrfilt) attrfiltParsed = read.table(con, sep="\t", header=FALSE, quote = "", comment.char = "", as.is=TRUE) close(con) if(type=="attributes"){ if(dim(attrfiltParsed)[2] < 3) stop("biomaRt error: looks like we're connecting to incompatible version of BioMart suite.") cnames = seq_len(dim(attrfiltParsed)[2]) cnames=paste(type,cnames,sep="") cnames[1] = "name" cnames[2] = "description" cnames[3] = "fullDescription" if(dim(attrfiltParsed)[2] < 4){ warning("biomaRt warning: looks like we're connecting to an older version of BioMart suite. Some biomaRt functions might not work.") } else{ cnames[4] = "page" } colnames(attrfiltParsed) = cnames } if(type=="filters"){ if(dim(attrfiltParsed)[2] < 4) stop("biomaRt error: looks like we're connecting to incompatible version of BioMart suite.") cnames = seq(1:dim(attrfiltParsed)[2]) cnames=paste(type,cnames,sep="") cnames[1] = "name" cnames[2] = "description" cnames[3] = "options" cnames[4] = "fullDescription" if(dim(attrfiltParsed)[2] < 7){ warning("biomaRt warning: looks like we're connecting to an older version of BioMart suite. Some biomaRt functions might not work.") } else{ cnames[5] = "filters" cnames[6] = "type" cnames[7] = "operation" } colnames(attrfiltParsed) = cnames } return(attrfiltParsed) } ## Select a BioMart dataset useDataset <- function(dataset, mart, verbose = FALSE){ if(missing(mart) || class(mart)!="Mart") stop("No valid Mart object given, specify a Mart object with the attribute mart") if(missing(dataset)) stop("No dataset given. Please use the dataset argument to specify which dataset you want to use. Correct dataset names can be obtained with the listDatasets function.") validDatasets=listDatasets(mart) if(is.na(match(dataset, validDatasets$dataset)))stop(paste("The given dataset: ",dataset,", is not valid. Correct dataset names can be obtained with the listDatasets function.")) martDataset(mart) = dataset if(verbose) messageToUser("Checking attributes ...") martAttributes(mart) <- bmAttrFilt("attributes",mart, verbose = verbose) if(verbose){ messageToUser(" ok\n") messageToUser("Checking filters ...") } martFilters(mart) <- bmAttrFilt("filters",mart, verbose = verbose) if(verbose) messageToUser(" ok\n") return( mart ) } ## getName getName <- function(x, pos) if(is.null(x[[pos]])) NA else x[[pos]] ## listAttributes listAttributes <- function(mart, page, what = c("name","description","page")) { martCheck(mart) if(!missing(page) && !page %in% attributePages(mart)) stop(paste("The chosen page: ",page," is not valid, please use the correct page name using the attributePages function",sep="")) attrib=NULL if(!missing(page)){ sel = which(martAttributes(mart)[,"page"] == page) attrib = martAttributes(mart)[sel,what] } else{ attrib = martAttributes(mart)[,what] } return(attrib) } ## attributePages attributePages <- function(mart){ martCheck(mart) pages = unique(martAttributes(mart)[,"page"]) return(pages) } ## listFilters listFilters <- function(mart, what = c("name", "description")) { martCheck(mart) filters = martFilters(mart) badwhat = !(what %in% colnames(filters)) if(any(badwhat)) stop(sprintf("The function argument 'what' contains %s: %s\nValid are: %s\n", if(sum(badwhat)>1) "invalid values" else "an invalid value", paste(what[badwhat], collapse=", "), paste(colnames(filters), collapse=", "))) return(filters[, what]) } ## filterOptions filterOptions <- function(filter, mart){ if(missing(filter)) stop("No filter given. Please specify the filter for which you want to retrieve the possible values.") if(class(filter)!="character")stop("Filter argument should be of class character") martCheck(mart) if(!filter %in% listFilters(mart, what="name"))stop("Filter not valid, check for typo in filter argument.") sel = which(listFilters(mart, what="name") == filter) return(listFilters(mart,what="options")[sel]) } ## filterType filterType <- function(filter, mart){ if(missing(filter)) stop("No filter given. Please specify the filter for which you want to retrieve the filter type") if(class(filter)!="character")stop("Filter argument should be of class character") martCheck(mart) type="unknown" sel = which(listFilters(mart, what="name") == filter) if(is.null(sel))stop(paste("Invalid filter",filter, sep=": ")) type = listFilters(mart,what="type")[sel] return(type) } ########################################## #getBM: generic BioMart query function # ########################################## getBM <- function(attributes, filters = "", values = "", mart, curl = NULL, checkFilters = TRUE, verbose=FALSE, uniqueRows=TRUE, bmHeader=FALSE, quote="\""){ martCheck(mart) if(missing( attributes )) stop("Argument 'attributes' must be specified.") if(is.list(filters) && !missing( values )) warning("Argument 'values' should not be used when argument 'filters' is a list and will be ignored.") if(is.list(filters) && is.null(names(filters))) stop("Argument 'filters' must be a named list when sent as a list.") if(!is.list(filters) && filters != "" && missing( values )) stop("Argument 'values' must be specified.") if(length(filters) > 0 && length(values) == 0) stop("Values argument contains no data.") if(is.list(filters)){ values = filters filters = names(filters) } if(class(uniqueRows) != "logical") stop("Argument 'uniqueRows' must be a logical value, so either TRUE or FALSE") xmlQuery = paste(" ",sep="") #checking the Attributes invalid = !(attributes %in% listAttributes(mart, what="name")) if(any(invalid)) stop(paste("Invalid attribute(s):", paste(attributes[invalid], collapse=", "), "\nPlease use the function 'listAttributes' to get valid attribute names")) #check if attributes come from multiple attribute pages currently disabled until ID issue resovled at Ensembl if(FALSE){ att = listAttributes(mart, what=c("name","page")) att = att[which(att[,1] %in% attributes),] attOK = FALSE pages = unique(att[,2]) if(length(pages) <= 1){ attOK = TRUE } else{ for(page in pages){ if(length(attributes) == length(which(attributes %in% att[which(att[,2] == page),1]))) attOK = TRUE } } if(!attOK){ stop(paste("Querying attributes from multiple attribute pages is not allowed. To see the attribute pages attributes belong to, use the function attributePages.")) } } #attribute are ok lets add them to the query attributeXML = paste("", collapse="", sep="") #checking the filters if(filters[1] != "" && checkFilters){ invalid = !(filters %in% listFilters(mart, what="name")) if(any(invalid)) stop(paste("Invalid filters(s):", paste(filters[invalid], collapse=", "), "\nPlease use the function 'listFilters' to get valid filter names")) } filterXML = NULL if(length(filters) > 1){ if(class(values)!= "list")stop("If using multiple filters, the 'value' has to be a list.\nFor example, a valid list for 'value' could be: list(affyid=c('1939_at','1000_at'), chromosome= '16')\nHere we select on Affymetrix identifier and chromosome, only results that pass both filters will be returned"); for(i in seq(along = filters)){ if(filters[i] %in% listFilters(mart, what = "name")){ filtertype=filterType(filters[i], mart) if(filtertype == 'boolean' || filtertype == 'boolean_list'){ if(!is.logical(values[[i]])) stop(paste("biomaRt error: ",filters[i]," is a boolean filter and needs a corresponding logical value of TRUE or FALSE to indicate if the query should retrieve all data that fulfill the boolean or alternatively that all data that not fulfill the requirement should be retrieved."), sep="") if(!values[[i]]){ values[[i]] = 1 } else{ values[[i]] = 0 } filterXML = paste(filterXML,paste("", collapse="",sep=""),sep="") } else{ if(is.numeric(values[[i]])){ values[[i]] = as.integer(values[[i]])} valuesString = paste(values[[i]],"",collapse=",",sep="") filterXML = paste(filterXML,paste("", collapse="",sep=""),sep="") } } else{ #used for attributes with values as these are treated as filters in BioMart valuesString = paste(values[[i]],"",collapse=",",sep="") filterXML = paste(filterXML,paste("", collapse="",sep=""),sep="") } } } else{ if(filters != ""){ if(is.list(values)){ values = unlist(values) } if(filters %in% listFilters(mart, what="name")){ filtertype =filterType(filters, mart) if(filtertype == 'boolean' || filtertype == 'boolean_list'){ if(!is.logical(values)) stop(paste("biomaRt error: ",filters," is a boolean filter and needs a corresponding logical value of TRUE or FALSE to indicate if the query should retrieve all data that fulfill the boolean or alternatively that all data that not fulfill the requirement should be retrieved."), sep="") if(!values){ values = 1 } else{ values = 0 } filterXML = paste("", collapse="",sep="") } else{ if(is.numeric(values)){ values = as.integer(values) } valuesString = paste(values,"",collapse=",",sep="") filterXML = paste("", collapse="",sep="") } } else{ #used for attributes with values as these are treated as filters in BioMart valuesString = paste(values,"",collapse=",",sep="") filterXML = paste(filterXML,paste("", collapse="",sep=""),sep="") } } else{ filterXML="" } } xmlQuery = paste(xmlQuery, attributeXML, filterXML,"",sep="") if(verbose){ cat(paste(xmlQuery,"\n", sep="")) } postRes = tryCatch(postForm(paste(martHost(mart),"?",sep=""),"query" = xmlQuery), error = function(e){stop("Request to BioMart web service failed. Verify if you are still connected to the internet. Alternatively the BioMart web service is temporarily down.")}) if(verbose){ writeLines("#################\nResults from server:") print(postRes) } if(!(is.character(postRes) && (length(postRes)==1L))) stop("The query to the BioMart webservice returned an invalid result: biomaRt expected a character string of length 1. Please report this to the mailing list.") if(gsub("\n", "", postRes, fixed = TRUE, useBytes = TRUE) == "") { # meaning an empty result result = as.data.frame(matrix("", ncol=length(attributes), nrow=0), stringsAsFactors=FALSE) } else { if(length(grep("^Query ERROR", postRes))>0L) stop(postRes) ## convert the serialized table into a dataframe con = textConnection(postRes) result = read.table(con, sep="\t", header=bmHeader, quote = quote, comment.char = "", check.names = FALSE, stringsAsFactors=FALSE) if(verbose){ writeLines("#################\nParsed results:") print(result) } close(con) if(!(is(result, "data.frame") && (ncol(result)==length(attributes)))) { print(head(result)) stop("The query to the BioMart webservice returned an invalid result: the number of columns in the result table does not equal the number of attributes in the query. Please report this to the mailing list.") } } if(!bmHeader){ #assumes order of results same as order of attibutes in input colnames(result) = attributes } else{ toAttributeName=FALSE if(toAttributeName){ #set to TRUE if attempting to replace attribute descriptions with attribute names att = listAttributes(mart) resultNames = colnames(result) for(r in 1:length(resultNames)){ asel = which(att[,2] == resultNames[r]) if(length(asel) == 1){ resultNames[r] = att[asel,1] } } colnames(result) = resultNames } } return(result) } ################################### #getLDS: Multiple dataset linking # ################################### getLDS <- function(attributes, filters = "", values = "", mart, attributesL, filtersL = "", valuesL = "", martL, verbose = FALSE, uniqueRows = TRUE, bmHeader = TRUE) { martCheck(mart) martCheck(martL) invalid = !(attributes %in% listAttributes(mart, what="name")) if(any(invalid)) stop(paste("Invalid attribute(s):", paste(attributes[invalid], collapse=", "), "\nPlease use the function 'listAttributes' to get valid attribute names")) invalid = !(attributesL %in% listAttributes(martL, what="name")) if(any(invalid)) stop(paste("Invalid attribute(s):", paste(attributesL[invalid], collapse=", "), "\nPlease use the function 'listAttributes' to get valid attribute names")) if(filters[1] != ""){ invalid = !(filters %in% listFilters(mart, what="name")) if(any(invalid)) stop(paste("Invalid filters(s):", paste(filters[invalid], collapse=", "), "\nPlease use the function 'listFilters' to get valid filter names")) } if(filtersL[1] != ""){ invalid = !(filtersL %in% listFilters(martL, what="name")) if(any(invalid)) stop(paste("Invalid filters(s):", paste(filtersL[invalid], collapse=", "), "\nPlease use the function 'listFilters' to get valid filter names")) } xmlQuery = paste(" ",sep="") attributeXML = paste("", collapse="", sep="") if(length(filters) > 1){ if(class(values)!= "list") stop("If using multiple filters, the 'value' has to be a list.\nFor example, a valid list for 'value' could be: list(affyid=c('1939_at','1000_at'), chromosome= '16')\nHere we select on affyid and chromosome, only results that pass both filters will be returned"); filterXML = NULL for(i in seq(along=filters)){ if(filterType(filters[i],mart) == 'boolean' || filterType(filters[i],mart) == 'boolean_list'){ if(!is.logical(values[[i]])) stop(paste("biomaRt error: ",filters[i]," is a boolean filter and needs a corresponding logical value of TRUE or FALSE to indicate if the query should retrieve all data that fulfill the boolean or alternatively that all data that not fulfill the requirement should be retrieved."), sep="") if(!values[[i]]){ values[[i]] = 1 } else{ values[[i]] = 0 } filterXML = paste(filterXML,paste("", collapse="",sep=""),sep="") } else{ valuesString = paste(values[[i]],"",collapse=",",sep="") filterXML = paste(filterXML,paste("", collapse="",sep=""),sep="") } } } else{ if(filters != ""){ if(filterType(filters,mart) == 'boolean' || filterType(filters,mart) == 'boolean_list'){ if(!is.logical(values)) stop(paste("biomaRt error: ",filters," is a boolean filter and needs a corresponding logical value of TRUE or FALSE to indicate if the query should retrieve all data that fulfill the boolean or alternatively that all data that not fulfill the requirement should be retrieved."), sep="") if(!values){ values = 1 } else{ values = 0 } filterXML = paste("", collapse="",sep="") } else{ valuesString = paste(values,"",collapse=",",sep="") filterXML = paste("", collapse="",sep="") } } else{ filterXML="" } } xmlQuery = paste(xmlQuery, attributeXML, filterXML,"",sep="") xmlQuery = paste(xmlQuery, "", sep="") linkedAttributeXML = paste("", collapse="", sep="") if(length(filtersL) > 1){ if(class(valuesL)!= "list") stop("If using multiple filters, the 'value' has to be a list.\nFor example, a valid list for 'value' could be: list(affyid=c('1939_at','1000_at'), chromosome= '16')\nHere we select on affyid and chromosome, only results that pass both filters will be returned"); linkedFilterXML = NULL for(i in seq(along=filtersL)){ if(filterType(filtersL,martL) == 'boolean' || filterType(filtersL,martL) == 'boolean_list'){ if(!is.logical(valuesL[[i]])) stop(paste("biomaRt error: ",filtersL[i]," is a boolean filter and needs a corresponding logical value of TRUE or FALSE to indicate if the query should retrieve all data that fulfill the boolean or alternatively that all data that not fulfill the requirement should be retrieved."), sep="") if(!valuesL[[i]]){ valuesL[[i]] = 1 } else{ valuesL[[i]] = 0 } linkedFilterXML = paste(linkedFilterXML,paste("", collapse="",sep=""),sep="") } else{ valuesString = paste(valuesL[[i]],"",collapse=",",sep="") linkedFilterXML = paste(linkedFilterXML,paste("", collapse="",sep=""),sep="") } } } else{ if(filtersL != ""){ if(filterType(filtersL,martL) == 'boolean' || filterType(filtersL,martL) == 'boolean_list'){ if(!is.logical(valuesL)) stop(paste("biomaRt error: ",filtersL," is a boolean filter and needs a corresponding logical value of TRUE or FALSE to indicate if the query should retrieve all data that fulfill the boolean or alternatively that all data that not fulfill the requirement should be retrieved."), sep="") if(!valuesL){ valuesL = 1 } else{ valuesL = 0 } linkedFilterXML = paste("", collapse="",sep="") } else{ valuesString = paste(valuesL,"",collapse=",",sep="") linkedFilterXML = paste("", collapse="",sep="") } } else{ linkedFilterXML="" } } xmlQuery = paste(xmlQuery, linkedAttributeXML, linkedFilterXML,"",sep="") if(verbose){ cat(paste(xmlQuery,"\n", sep="")) } postRes = postForm(paste(martHost(mart),"?",sep=""),"query"=xmlQuery) ## 10-01-2014 if(length(grep("^Query ERROR", postRes))>0L) stop(postRes) ## if(postRes != ""){ con = textConnection(postRes) result = read.table(con, sep="\t", header=bmHeader, quote = "\"", comment.char = "", as.is=TRUE, check.names = TRUE) close(con) if(all(is.na(result[,ncol(result)]))) result = result[,-ncol(result),drop=FALSE] ## 10 - 01 - 2014 res_attributes <- c(attributes,attributesL) if(!(is(result, "data.frame") && (ncol(result)==length(res_attributes)))) { print(head(result)) stop("The query to the BioMart webservice returned an invalid result: the number of columns in the result table does not equal the number of attributes in the query. Please report this to the mailing list.") } if(!bmHeader){ #assumes order of results same as order of attibutes in input colnames(result) = res_attributes ## } } else { warning("getLDS returns NULL.") result=NULL } return(result) } ###################### #getXML ###################### getXML <- function(host="http://www.biomart.org/biomart/martservice?", xmlquery){ pf = postForm(host,"query"=xmlquery) con = textConnection(pf) result = read.table(con, sep="\t", header=FALSE, quote = "", comment.char = "", as.is=TRUE) close(con) return(result) } ###################### #getBMlist ###################### getBMlist <- function(attributes, filters = "", values = "", mart, list.names = NULL, na.value = NA, verbose=FALSE, giveWarning=TRUE){ if(giveWarning) writeLines("Performing your query using getBM is preferred as getBMlist perfoms a separate getBM query for each of the values one gives. This is ok for a short list but will definitely fail when used with longer lists. Ideally one does a batch query with getBM and then iterates over that result.") out <- vector("list", length(attributes)) if(is.null(list.names)) names(out) <- attributes else names(out) <- list.names for(j in seq(along = attributes)){ tmp2 <- vector("list", length(values)) names(tmp2) <- values for(k in seq(along = tmp2)){ tst <- getBM(attributes = attributes[j], filters=filters, values = values[k], mart = mart, verbose = verbose) if(class(tst) == "data.frame"){ tmp <- unlist(unique(tst[!is.na(tst)]), use.names = FALSE) if(length(tmp) > 0) tmp2[[k]] <- tmp else tmp2[[k]] <- na.value }else{ tmp2[[k]] <- na.value } out[[j]] <- tmp2 } } return(out) } ############################### # # #Ensembl specific functions # ############################### listEnsembl <- function(mart = NULL, host="www.ensembl.org",version = NULL, GRCh = NULL, mirror = NULL,verbose = FALSE){ if(!is.null(mirror) & (!is.null(version) | !is.null(GRCh))){ warning("version or GRCh arguments can not be used together with the mirror argument. Will ignore the mirror argument and connect to default ensembl host") mirror = NULL } if(!is.null(version)){ host = paste("e",version,".ensembl.org",sep="") } if(!is.null(GRCh)){ if(GRCh == 37){ host = paste("grch",GRCh,".ensembl.org",sep="") } else{ print("Only 37 can be specified for GRCh version") } } if(!is.null(mirror)){ if(!(mirror %in% c("uswest","useast","asia"))){ warning("Invalid mirror select a mirror from [uswest,useast,asia], default when no mirror is specified points to main ensembl hosted in the UK") } else{ if(mirror == "uswest"){ host = "uswest.ensembl.org" } if(mirror == "useast"){ host == "useast.ensembl.org" } if(mirror == "asia"){ host = "asia.ensembl.org" } } } marts = listMarts(mart = mart, host = host, verbose = verbose) sel = which(marts$biomart == "ENSEMBL_MART_ENSEMBL") if(length(sel) > 0){ marts$biomart[sel] = "ensembl" } sel = which(marts$biomart == "ENSEMBL_MART_SNP") if(length(sel) > 0){ marts$biomart[sel] = "snp" } sel = which(marts$biomart == "ENSEMBL_MART_FUNCGEN") if(length(sel) > 0){ marts$biomart[sel] = "regulation" } sel = which(marts$biomart == "ENSEMBL_MART_VEGA") if(length(sel) > 0){ marts$biomart[sel] = "vega" } return(marts) } useEnsembl <- function(biomart, dataset,host = "www.ensembl.org", version = NULL, GRCh = NULL,mirror = NULL ,verbose = FALSE){ if(!is.null(mirror) & (!is.null(version) | !is.null(GRCh))){ warning("version or GRCh arguments can not be used together with the mirror argument. Will ignore the mirror argument and connect to default ensembl host") mirror = NULL } if(!is.null(version)){ host = paste("e",version,".ensembl.org",sep="") } if(!is.null(GRCh)){ if(GRCh == 37){ host = paste("grch",GRCh,".ensembl.org",sep="") } else{ print("Only 37 can be specified for GRCh version") } } if(!is.null(mirror)){ if(!(mirror %in% c("uswest","useast","asia"))){ warning("Invalid mirror select a mirror from [uswest,useast,asia], default when no mirror is specified points to main ensembl hosted in the UK") } else{ if(mirror == "uswest"){ host = "uswest.ensembl.org" } if(mirror == "useast"){ host == "useast.ensembl.org" } if(mirror == "asia"){ host = "asia.ensembl.org" } } } if(biomart == "ensembl"){ biomart = "ENSEMBL_MART_ENSEMBL" } if(biomart == "snp"){ biomart = "ENSEMBL_MART_SNP" } if(biomart == "regulation"){ biomart = "ENSEMBL_MART_FUNCGEN" } if(biomart == "vega"){ biomart = "ENSEMBL_MART_VEGA" } ens = useMart(biomart = biomart, dataset = dataset, host = host, verbose = verbose) return(ens) } getGene <- function( id, type, mart){ martCheck(mart,"ensembl") checkWrapperArgs(id, type, mart) symbolAttrib = switch(strsplit(martDataset(mart), "_", fixed = TRUE, useBytes = TRUE)[[1]][1],hsapiens = "hgnc_symbol",mmusculus = "mgi_symbol","external_gene_id") typeAttrib = switch(type,affy_hg_u133a_2 = "affy_hg_u133a_v2",type) attrib = c(typeAttrib,symbolAttrib,"description","chromosome_name","band","strand","start_position","end_position","ensembl_gene_id") table = getBM(attributes = attrib,filters = type, values = id, mart=mart) return(table) } getSequence <- function(chromosome, start, end, id, type, seqType, upstream, downstream, mart, verbose=FALSE){ martCheck(mart,c("ensembl","ENSEMBL_MART_ENSEMBL")) if(missing(seqType) || !seqType %in% c("cdna","peptide","3utr","5utr", "gene_exon", "transcript_exon","transcript_exon_intron","gene_exon_intron","coding","coding_transcript_flank","coding_gene_flank","transcript_flank","gene_flank")){ stop("Please specify the type of sequence that needs to be retrieved when using biomaRt in web service mode. Choose either gene_exon, transcript_exon,transcript_exon_intron, gene_exon_intron, cdna, coding,coding_transcript_flank,coding_gene_flank,transcript_flank,gene_flank,peptide, 3utr or 5utr") } if(missing(type))stop("Please specify the type argument. If you use chromosomal coordinates to retrieve sequences, then the type argument will specify the type of gene indentifiers that you will retrieve with the sequences. If you use a vector of identifiers to retrieve the sequences, the type argument specifies the type of identifiers you are using.") if(missing(id) && missing(chromosome) && !missing(type))stop("No vector of identifiers given. Please use the id argument to give a vector of identifiers for which you want to retrieve the sequences.") if(!missing(chromosome) && !missing(id))stop("The getSequence function retrieves sequences given a vector of identifiers specified with the id argument of a type specified by the type argument. Or alternatively getSequence retrieves sequences given a chromosome, a start and a stop position on the chromosome. As you specified both a vector of identifiers and chromsomal coordinates. Your query won't be processed.") if(!missing(chromosome)){ if(!missing(start) && missing(end))stop("You specified a chromosomal start position but no end position. Please also specify a chromosomal end position.") if(!missing(end) && missing(start))stop("You specified a chromosomal end position but no start position. Please also specify a chromosomal start position.") if(!missing(start)){ start = as.integer(start) end = as.integer(end) } if(missing(upstream) && missing(downstream)){ sequence = getBM(c(seqType,type), filters = c("chromosome_name","start","end"), values = list(chromosome, start, end), mart = mart, checkFilters = FALSE, verbose=verbose) } else{ if(!missing(upstream) && missing(downstream)){ sequence = getBM(c(seqType,type), filters = c("chromosome_name","start","end","upstream_flank"), values = list(chromosome, start, end, upstream), mart = mart, checkFilters = FALSE, verbose=verbose) } if(!missing(downstream) && missing(upstream)){ sequence = getBM(c(seqType,type), filters = c("chromosome_name","start","end","downstream_flank"), values = list(chromosome, start, end, downstream), mart = mart, checkFilters = FALSE, verbose = verbose) } if(!missing(downstream) && !missing(upstream)){ stop("Currently getSequence only allows the user to specify either an upstream of a downstream argument but not both.") } } } if(!missing(id)){ if(missing(type)) stop("Type argument is missing. This will be used to retrieve an identifier along with the sequence so one knows which gene it is from. Use the listFilters function to select a valid type argument.") if(!type %in% listFilters(mart, what="name")) stop("Invalid type argument. Use the listFilters function to select a valid type argument.") valuesString = paste(id,"",collapse=",",sep="") if(missing(upstream) && missing(downstream)){ sequence = getBM(c(seqType,type), filters = type, values = id, mart = mart, verbose=verbose) } else{ if(!missing(upstream) && missing(downstream)){ sequence = getBM(c(seqType,type), filters = c(type, "upstream_flank"), values = list(id, upstream), mart = mart, checkFilters = FALSE, verbose=verbose) } if(!missing(downstream) && missing(upstream)){ sequence = getBM(c(seqType,type), filters = c(type, "downstream_flank"), values = list(id, downstream), mart = mart, checkFilters = FALSE, verbose=verbose) } if(!missing(downstream) && !missing(upstream)){ stop("Currently getSequence only allows the user to specify either an upstream of a downstream argument but not both.") } } } return(sequence) } #################### #export FASTA # #################### exportFASTA <- function( sequences, file ){ if( missing( sequences ) || class( sequences ) != "data.frame"){ stop("No data.frame given to write FASTA. The data.frame should be the output of the getSequence function."); } if( missing(file)){ stop("Please provide filename to write to"); } if(length(sequences[1,]) == 2){ for(i in seq(along = sequences[,2])){ cat(paste(">",sequences[i,2],"\n",sep=""),file = file, append=TRUE); cat(as.character(sequences[i,1]),file = file, append = TRUE); cat("\n\n", file = file, append = TRUE); } } else{ for(i in seq(along = sequences[,2])){ cat(paste(">chromosome_",sequences[i,1],"_start_",sequences[i,2],"_end_",sequences[i,3],"\n",sep=""),file = file, append=TRUE); cat(as.character(sequences[i,4]),file = file, append = TRUE); cat("\n\n", file = file, append = TRUE); } } } ################### #Nature Protocol ################### NP2009code <- function(){ edit(file=system.file('scripts', 'Integration-NP.R', package = 'biomaRt')) } biomaRt/R/biomaRtClasses.R0000644000175400017540000000105713001231112016417 0ustar00biocbuildbiocbuildsetClass("Mart", representation(biomart = "character", host = "character", vschema = "character", version = "character", dataset = "character", filters = "data.frame", attributes = "data.frame", archive = "logical" ), prototype(dataset = "", vschema="default", archive = FALSE ) ); biomaRt/R/methods-Mart.R0000644000175400017540000000760713001231112016057 0ustar00biocbuildbiocbuildsetMethod("show",signature(object="Mart"), function(object){ res = paste("Object of class 'Mart':\n Using the ",object@biomart," BioMart database\n Using the ",object@dataset," dataset\n", sep="") cat(res) }) setGeneric("martBM",def=function(obj,...) standardGeneric("martBM")) setMethod("martBM",signature("Mart"), function(obj) obj@biomart) setGeneric("martBM<-", function(obj, value) standardGeneric("martBM<-")) setReplaceMethod("martBM","Mart",function(obj,value){ obj@biomart <- value obj }) setGeneric("martAttributes",def=function(obj,...)standardGeneric("martAttributes")) setMethod("martAttributes",signature("Mart"),function(obj) obj@attributes) setGeneric("martAttributes<-", function(obj, value) standardGeneric("martAttributes<-")) setReplaceMethod("martAttributes","Mart",function(obj,value){ obj@attributes <- value obj }) setGeneric("martAttribPointers",def=function(obj,...)standardGeneric("martAttribPointers")) setMethod("martAttribPointers",signature("Mart"),function(obj) obj@attributePointer) setGeneric("martAttribPointers<-", function(obj, value) standardGeneric("martAttribPointers<-")) setReplaceMethod("martAttribPointers","Mart",function(obj,value){ obj@attributePointer <- value obj }) setGeneric("martFilters",def=function(obj,...)standardGeneric("martFilters")) setMethod("martFilters",signature("Mart"),function(obj) obj@filters) setGeneric("martFilters<-", function(obj, value) standardGeneric("martFilters<-")) setReplaceMethod("martFilters","Mart",function(obj,value){ obj@filters <- value obj }) setGeneric("martDataset",def=function(obj,...)standardGeneric("martDataset")) setMethod("martDataset",signature("Mart"), function(obj) obj@dataset) setGeneric("martDataset<-", function(obj, value) standardGeneric("martDataset<-")) setReplaceMethod("martDataset","Mart",function(obj,value){ obj@dataset <- value obj }) setGeneric("martHost",def=function(obj,...)standardGeneric("martHost")) setMethod("martHost",signature("Mart"), function(obj) obj@host) setGeneric("martArchive",def=function(obj,...)standardGeneric("martArchive")) setMethod("martArchive",signature("Mart"), function(obj) obj@archive) setGeneric("martVSchema",def=function(obj,...)standardGeneric("martVSchema")) setMethod("martVSchema",signature("Mart"), function(obj) obj@vschema) setGeneric("martVSchema<-", function(obj, value) standardGeneric("martVSchema<-")) setReplaceMethod("martVSchema","Mart",function(obj,value){ obj@vschema <- value obj }) ##################################################################### ## new wrappers to enable keys, columns, select and keytypes .keys <- function(x, keytype){ res <- filterOptions(filter=keytype, mart=x) res <- sub("\\]$","",res) res <- sub("^\\[","",res) unlist(strsplit(res, split=",")) } setMethod("keys", "Mart", function(x, keytype, ...){ AnnotationDbi:::smartKeys(x=x, keytype=keytype, ..., FUN=biomaRt:::.keys) } ) setMethod("keytypes", "Mart", function(x) listFilters(mart=x)[["name"]] ) setMethod("columns", "Mart", function(x) listAttributes(mart=x)[["name"]] ) ## Arg checking is similar (but more limited) to what is done for getBM setMethod("select", "Mart", function(x, keys, columns, keytype, ...){ if(missing( columns )) stop("Argument 'columns' must be specified.") if(!is.list(keytype) && keytype != "" && missing( keys )) stop("Argument 'keys' must be specified.") if(length(keytype) > 0 && length(keys) == 0) stop("Keys argument contains no data.") if(!(is.character(keytype)) || length(keytype)!=1){ stop("keytype should be single element character vector.") } getBM(attributes=columns, filters=keytype, values=keys, mart=x) } ) biomaRt/build/0000755000175400017540000000000013001246365014274 5ustar00biocbuildbiocbuildbiomaRt/build/vignette.rds0000644000175400017540000000032413001246365016632 0ustar00biocbuildbiocbuildb```b`ffd`b2 1# 'NM * MAHUJ++f)すQ& 7aD0!)dKM-FZ]?4-ީE0=(jؠjX2sRad9.nP&c0Gq?gQ~poݣ9JI,IK+VwbiomaRt/inst/0000755000175400017540000000000013001246365014152 5ustar00biocbuildbiocbuildbiomaRt/inst/CITATION0000644000175400017540000000342513001231112015273 0ustar00biocbuildbiocbuildcitHeader("To cite the biomaRt package in publications use:") citEntry(entry="article", title = "Mapping identifiers for the integration of genomic datasets with the R/Bioconductor package biomaRt", author = personList(person(given="Steffen", family="Durinck"), person(given="Paul T.", family="Spellman"), person(given="Ewan", family="Birney"), person(given="Wolfgang", family="Huber")), journal = "Nature Protocols", year = "2009", volume = "4", pages = "1184--1191", textVersion = paste("Mapping identifiers for the integration of genomic datasets with the R/Bioconductor package biomaRt.", "Steffen Durinck, Paul T. Spellman, Ewan Birney and Wolfgang Huber,", "Nature Protocols 4, 1184-1191 (2009).")) citEntry(entry="article", title = "BioMart and Bioconductor: a powerful link between biological databases and microarray data analysis", author = personList(person(given="Steffen", family="Durinck"), person(given="Yves", family="Moreau"), person(given="Arek", family="Kasprzyk"), person(given="Sean", family="Davis"), person(given="Bart", family="De Moor"), person(given="Alvis", family="Brazma"), person(given="Wolfgang", family="Huber")), journal = "Bioinformatics",, year = "2005", volume = "21", pages = "3439--3440", textVersion = paste("BioMart and Bioconductor: a powerful link between biological databases and microarray data analysis.", "Steffen Durinck, Yves Moreau, Arek Kasprzyk, Sean Davis, Bart De Moor, Alvis Brazma and Wolfgang Huber,", "Bioinformatics 21, 3439-3440 (2005).")) biomaRt/inst/doc/0000755000175400017540000000000013001246365014717 5ustar00biocbuildbiocbuildbiomaRt/inst/doc/biomaRt.R0000644000175400017540000002201613001246365016440 0ustar00biocbuildbiocbuild## ----setup, cache = F, echo = FALSE-------------------------------------- knitr::opts_chunk$set(error = TRUE) ## ----annotate,echo=FALSE---------------------------------------------------------------------------------------------- ## library("annotate") options(width=120) ## ----biomaRt---------------------------------------------------------------------------------------------------------- library("biomaRt") listMarts() ## ----putenv, eval = FALSE--------------------------------------------------------------------------------------------- # Sys.setenv("http_proxy" = "http://my.proxy.org:9999") ## ----rCurlOptions, eval = FALSE--------------------------------------------------------------------------------------- # options(RCurlOptions = list(proxy="uscache.kcc.com:80",proxyuserpwd="------:-------")) ## ----ensembl1--------------------------------------------------------------------------------------------------------- ensembl=useMart("ensembl") ## ----listDatasets----------------------------------------------------------------------------------------------------- listDatasets(ensembl) ## ----ensembl2, eval=TRUE---------------------------------------------------------------------------------------------- ensembl = useDataset("hsapiens_gene_ensembl",mart=ensembl) ## ----ensembl3--------------------------------------------------------------------------------------------------------- ensembl = useMart("ensembl",dataset="hsapiens_gene_ensembl") ## ----filters---------------------------------------------------------------------------------------------------------- filters = listFilters(ensembl) filters[1:5,] ## ----attributes------------------------------------------------------------------------------------------------------- attributes = listAttributes(ensembl) attributes[1:5,] ## ----getBM1, echo=TRUE,eval=TRUE-------------------------------------------------------------------------------------- affyids=c("202763_at","209310_s_at","207500_at") getBM(attributes=c('affy_hg_u133_plus_2', 'entrezgene'), filters = 'affy_hg_u133_plus_2', values = affyids, mart = ensembl) ## ----task1, echo=TRUE,eval=TRUE--------------------------------------------------------------------------------------- affyids=c("202763_at","209310_s_at","207500_at") getBM(attributes = c('affy_hg_u133_plus_2', 'hgnc_symbol', 'chromosome_name', 'start_position', 'end_position', 'band'), filters = 'affy_hg_u133_plus_2', values = affyids, mart = ensembl) ## ----task2, echo=TRUE,eval=TRUE--------------------------------------------------------------------------------------- entrez=c("673","837") goids = getBM(attributes = c('entrezgene', 'go_id'), filters = 'entrezgene', values = entrez, mart = ensembl) head(goids) ## ----task3, echo=TRUE,eval=TRUE--------------------------------------------------------------------------------------- go=c("GO:0051330","GO:0000080","GO:0000114","GO:0000082") chrom=c(17,20,"Y") getBM(attributes= "hgnc_symbol", filters=c("go_id","chromosome_name"), values=list(go, chrom), mart=ensembl) ## ----task4, echo=TRUE,eval=TRUE--------------------------------------------------------------------------------------- refseqids = c("NM_005359","NM_000546") ipro = getBM(attributes=c("refseq_mrna","interpro","interpro_description"), filters="refseq_mrna", values=refseqids, mart=ensembl) ipro ## ----task5, eval = TRUE----------------------------------------------------------------------------------------------- getBM(attributes = c('affy_hg_u133_plus_2','ensembl_gene_id'), filters = c('chromosome_name','start','end'), values = list(16,1100000,1250000), mart = ensembl) ## ----task6, echo=TRUE, eval = TRUE------------------------------------------------------------------------------------ getBM(attributes = c('entrezgene','hgnc_symbol'), filters = 'go_id', values = 'GO:0004707', mart = ensembl) ## ----task7, eval=TRUE------------------------------------------------------------------------------------------------- entrez=c("673","7157","837") getSequence(id = entrez, type="entrezgene", seqType="coding_gene_flank", upstream=100, mart=ensembl) ## ----task8, echo=TRUE,eval=TRUE--------------------------------------------------------------------------------------- utr5 = getSequence(chromosome=3, start=185514033, end=185535839, type="entrezgene", seqType="5utr", mart=ensembl) utr5 ## ----task9, echo=TRUE, eval=TRUE-------------------------------------------------------------------------------------- protein = getSequence(id=c(100, 5728), type="entrezgene", seqType="peptide", mart=ensembl) protein ## ----task10, echo=TRUE, eval=TRUE------------------------------------------------------------------------------------- snpmart = useMart(biomart = "ENSEMBL_MART_SNP", dataset="hsapiens_snp") ## ----task10b---------------------------------------------------------------------------------------------------------- getBM(attributes = c('refsnp_id','allele','chrom_start','chrom_strand'), filters = c('chr_name','start','end'), values = list(8,148350,148612), mart = snpmart) ## ----getLDS----------------------------------------------------------------------------------------------------------- human = useMart("ensembl", dataset = "hsapiens_gene_ensembl") mouse = useMart("ensembl", dataset = "mmusculus_gene_ensembl") getLDS(attributes = c("hgnc_symbol","chromosome_name", "start_position"), filters = "hgnc_symbol", values = "TP53",mart = human, attributesL = c("refseq_mrna","chromosome_name","start_position"), martL = mouse) ## ----archiveMarts1---------------------------------------------------------------------------------------------------- listMarts(archive = TRUE) ## ----archiveMarts2, echo = TRUE, eval = TRUE-------------------------------------------------------------------------- ensembl = useMart("ensembl_mart_46", dataset="hsapiens_gene_ensembl", archive = TRUE) ## ----archiveMarts3, echo = TRUE, eval = TRUE-------------------------------------------------------------------------- listMarts(host='may2009.archive.ensembl.org') ensembl54=useMart(host='may2009.archive.ensembl.org', biomart='ENSEMBL_MART_ENSEMBL') ensembl54=useMart(host='may2009.archive.ensembl.org', biomart='ENSEMBL_MART_ENSEMBL', dataset='hsapiens_gene_ensembl') ## ----wormbase, echo=TRUE, eval=TRUE----------------------------------------------------------------------------------- listMarts(host = "parasite.wormbase.org") wormbase = useMart(biomart = "parasite_mart", host = "parasite.wormbase.org") listDatasets(wormbase) wormbase <- useDataset(mart = wormbase, dataset = "wbps_gene") head(listFilters(wormbase)) head(listAttributes(wormbase)) getBM(attributes = c("external_gene_id","ensembl_transcript_id","transcript_biotype"), filters="gene_name", values=c("unc-26","his-33"), mart=wormbase) ## ----filterType------------------------------------------------------------------------------------------------------- filterType("with_affy_hg_u133_plus_2",ensembl) ## ----filterOptions---------------------------------------------------------------------------------------------------- filterOptions("biotype",ensembl) ## ----attributePages--------------------------------------------------------------------------------------------------- pages = attributePages(ensembl) pages ## ----listAttributes--------------------------------------------------------------------------------------------------- head(listAttributes(ensembl, page="feature_page")) ## ----localCopy, eval = FALSE------------------------------------------------------------------------------------------ # listMarts(host="www.myLocalHost.org", path="/myPathToWebservice/martservice") # mart=useMart("nameOfMyMart",dataset="nameOfMyDataset",host="www.myLocalHost.org", path="/myPathToWebservice/martservice") ## ----columnsAndKeyTypes----------------------------------------------------------------------------------------------- mart <- useMart(dataset="hsapiens_gene_ensembl",biomart='ensembl') head(keytypes(mart), n=3) head(columns(mart), n=3) ## ----keys1------------------------------------------------------------------------------------------------------------ k = keys(mart, keytype="chromosome_name") head(k, n=3) ## ----keys2------------------------------------------------------------------------------------------------------------ k = keys(mart, keytype="chromosome_name", pattern="LRG") head(k, n=3) ## ----select----------------------------------------------------------------------------------------------------------- affy=c("202763_at","209310_s_at","207500_at") select(mart, keys=affy, columns=c('affy_hg_u133_plus_2','entrezgene'), keytype='affy_hg_u133_plus_2') ## ----sessionInfo------------------------------------------------------------------------------------------------------ sessionInfo() warnings() biomaRt/inst/doc/biomaRt.Rmd0000644000175400017540000006330113001246365016763 0ustar00biocbuildbiocbuild--- title: "The biomaRt users guide" author: "Steffen Durinck, Wolfgang Huber, Mike Smith" package: "`r pkg_ver('biomaRt')`" output: BiocStyle::html_document: md_extensions: "-autolink_bare_uris" vignette: > %\VignetteIndexEntry{The biomaRt users guide} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, cache = F, echo = FALSE} knitr::opts_chunk$set(error = TRUE) ``` # Introduction In recent years a wealth of biological data has become available in public data repositories. Easy access to these valuable data resources and firm integration with data analysis is needed for comprehensive bioinformatics data analysis. The `r Biocpkg("biomaRt")` package, provides an interface to a growing collection of databases implementing the [BioMart software suite](http://www.biomart.org). The package enables retrieval of large amounts of data in a uniform way without the need to know the underlying database schemas or write complex SQL queries. Examples of BioMart databases are Ensembl, Uniprot and HapMap. These major databases give `r Biocpkg("biomaRt")` users direct access to a diverse set of data and enable a wide range of powerful online queries from R. # Selecting a BioMart database and dataset Every analysis with `r Biocpkg("biomaRt")` starts with selecting a BioMart database to use. A first step is to check which BioMart web services are available. The function `listMarts()` will display all available BioMart web services ```{r annotate,echo=FALSE} ## library("annotate") options(width=120) ``` ```{r biomaRt} library("biomaRt") listMarts() ``` Note: if the function `useMart()` runs into proxy problems you should set your proxy first before calling any `r Biocpkg("biomaRt")` functions. You can do this using the Sys.putenv command: ```{r putenv, eval = FALSE} Sys.setenv("http_proxy" = "http://my.proxy.org:9999") ``` Some users have reported that the workaround above does not work, in this case an alternative proxy solution below can be tried: ```{r rCurlOptions, eval = FALSE} options(RCurlOptions = list(proxy="uscache.kcc.com:80",proxyuserpwd="------:-------")) ``` The `useMart()` function can now be used to connect to a specified BioMart database, this must be a valid name given by `listMarts()`. In the next example we choose to query the Ensembl BioMart database. ```{r ensembl1} ensembl=useMart("ensembl") ``` BioMart databases can contain several datasets, for Ensembl every species is a different dataset. In a next step we look at which datasets are available in the selected BioMart by using the function `listDatasets()`. ```{r listDatasets} listDatasets(ensembl) ``` To select a dataset we can update the `Mart` object using the function `useDataset()`. In the example below we choose to use the hsapiens dataset. ```{r ensembl2, eval=TRUE} ensembl = useDataset("hsapiens_gene_ensembl",mart=ensembl) ``` Or alternatively if the dataset one wants to use is known in advance, we can select a BioMart database and dataset in one step by: ```{r ensembl3} ensembl = useMart("ensembl",dataset="hsapiens_gene_ensembl") ``` # How to build a biomaRt query The `getBM()` function has three arguments that need to be introduced: filters, attributes and values. *Filters* define a restriction on the query. For example you want to restrict the output to all genes located on the human X chromosome then the filter *chromosome_name* can be used with value 'X'. The `listFilters()` function shows you all available filters in the selected dataset. ```{r filters} filters = listFilters(ensembl) filters[1:5,] ``` *Attributes* define the values we are interested in to retrieve. For example we want to retrieve the gene symbols or chromosomal coordinates. The `listAttributes()` function displays all available attributes in the selected dataset. ```{r attributes} attributes = listAttributes(ensembl) attributes[1:5,] ``` The `getBM()` function is the main query function in `r Biocpkg("biomaRt")`. It has four main arguments: * `attributes`: is a vector of attributes that one wants to retrieve (= the output of the query). * `filters`: is a vector of filters that one wil use as input to the query. * `values`: a vector of values for the filters. In case multple filters are in use, the values argument requires a list of values where each position in the list corresponds to the position of the filters in the filters argument (see examples below). * `mart`: is an object of class `Mart`, which is created by the `useMart()` function. *Note: for some frequently used queries to Ensembl, wrapper functions are available: `getGene()` and `getSequence()`. These functions call the `getBM()` function with hard coded filter and attribute names.* Now that we selected a BioMart database and dataset, and know about attributes, filters, and the values for filters; we can build a `r Biocpkg("biomaRt")` query. Let's make an easy query for the following problem: We have a list of Affymetrix identifiers from the u133plus2 platform and we want to retrieve the corresponding EntrezGene identifiers using the Ensembl mappings. The u133plus2 platform will be the filter for this query and as values for this filter we use our list of Affymetrix identifiers. As output (attributes) for the query we want to retrieve the EntrezGene and u133plus2 identifiers so we get a mapping of these two identifiers as a result. The exact names that we will have to use to specify the attributes and filters can be retrieved with the `listAttributes()` and `listFilters()` function respectively. Let's now run the query: ```{r getBM1, echo=TRUE,eval=TRUE} affyids=c("202763_at","209310_s_at","207500_at") getBM(attributes=c('affy_hg_u133_plus_2', 'entrezgene'), filters = 'affy_hg_u133_plus_2', values = affyids, mart = ensembl) ``` # Examples of biomaRt queries In the sections below a variety of example queries are described. Every example is written as a task, and we have to come up with a `r Biocpkg("biomaRt")` solution to the problem. ## Annotate a set of Affymetrix identifiers with HUGO symbol and chromosomal locations of corresponding genes We have a list of Affymetrix hgu133plus2 identifiers and we would like to retrieve the HUGO gene symbols, chromosome names, start and end positions and the bands of the corresponding genes. The `listAttributes()` and the `listFilters()` functions give us an overview of the available attributes and filters and we look in those lists to find the corresponding attribute and filter names we need. For this query we'll need the following attributes: hgnc_symbol, chromsome_name, start_position, end_position, band and affy_hg_u133_plus_2 (as we want these in the output to provide a mapping with our original Affymetrix input identifiers. There is one filter in this query which is the affy_hg_u133_plus_2 filter as we use a list of Affymetrix identifiers as input. Putting this all together in the `getBM()` and performing the query gives: ```{r task1, echo=TRUE,eval=TRUE} affyids=c("202763_at","209310_s_at","207500_at") getBM(attributes = c('affy_hg_u133_plus_2', 'hgnc_symbol', 'chromosome_name', 'start_position', 'end_position', 'band'), filters = 'affy_hg_u133_plus_2', values = affyids, mart = ensembl) ``` ## Annotate a set of EntrezGene identifiers with GO annotation In this task we start out with a list of EntrezGene identiers and we want to retrieve GO identifiers related to biological processes that are associated with these entrezgene identifiers. Again we look at the output of `listAttributes()` and `listFilters()` to find the filter and attributes we need. Then we construct the following query: ```{r task2, echo=TRUE,eval=TRUE} entrez=c("673","837") goids = getBM(attributes = c('entrezgene', 'go_id'), filters = 'entrezgene', values = entrez, mart = ensembl) head(goids) ``` ## Retrieve all HUGO gene symbols of genes that are located on chromosomes 17,20 or Y, and are associated with specific GO terms The GO terms we are interested in are: **GO:0051330**, **GO:0000080**, **GO:0000114**, **GO:0000082**. The key to performing this query is to understand that the `getBM()` function enables you to use more than one filter at the same time. In order to do this, the filter argument should be a vector with the filter names. The values should be a list, where the first element of the list corresponds to the first filter and the second list element to the second filter and so on. The elements of this list are vectors containing the possible values for the corresponding filters. ```{r task3, echo=TRUE,eval=TRUE} go=c("GO:0051330","GO:0000080","GO:0000114","GO:0000082") chrom=c(17,20,"Y") getBM(attributes= "hgnc_symbol", filters=c("go_id","chromosome_name"), values=list(go, chrom), mart=ensembl) ``` ## Annotate set of idenfiers with INTERPRO protein domain identifiers In this example we want to annotate the following two RefSeq identifiers: **NM_005359** and **NM_000546** with INTERPRO protein domain identifiers and a description of the protein domains. ```{r task4, echo=TRUE,eval=TRUE} refseqids = c("NM_005359","NM_000546") ipro = getBM(attributes=c("refseq_mrna","interpro","interpro_description"), filters="refseq_mrna", values=refseqids, mart=ensembl) ipro ``` ## Select all Affymetrix identifiers on the hgu133plus2 chip and Ensembl gene identifiers for genes located on chromosome 16 between basepair 1100000 and 1250000. In this example we will again use multiple filters: *chromosome_name*, *start*, and *end* as we filter on these three conditions. Note that when a chromosome name, a start position and an end position are jointly used as filters, the BioMart webservice interprets this as return everything from the given chromosome between the given start and end positions. ```{r task5, eval = TRUE} getBM(attributes = c('affy_hg_u133_plus_2','ensembl_gene_id'), filters = c('chromosome_name','start','end'), values = list(16,1100000,1250000), mart = ensembl) ``` ## Retrieve all entrezgene identifiers and HUGO gene symbols of genes which have a "MAP kinase activity" GO term associated with it. The GO identifier for MAP kinase activity is **GO:0004707**. In our query we will use *go_id* as our filter, and *entrezgene* and *hgnc_symbol* as attributes. Here's the query: ```{r task6, echo=TRUE, eval = TRUE} getBM(attributes = c('entrezgene','hgnc_symbol'), filters = 'go_id', values = 'GO:0004707', mart = ensembl) ``` ## Given a set of EntrezGene identifiers, retrieve 100bp upstream promoter sequences All sequence related queries to Ensembl are available through the `getSequence()` wrapper function. `getBM()` can also be used directly to retrieve sequences but this can get complicated so using getSequence is recommended. Sequences can be retrieved using the `getSequence()` function either starting from chromosomal coordinates or identifiers. The chromosome name can be specified using the *chromosome* argument. The *start* and *end* arguments are used to specify *start* and *end* positions on the chromosome. The type of sequence returned can be specified by the *seqType* argument which takes the following values: * *cdna* * *peptide* for protein sequences * *3utr* for 3' UTR sequences * *5utr* for 5' UTR sequences * *gene_exon* for exon sequences only * *transcript_exon* for transcript specific exonic sequences only * *transcript_exon_intron* gives the full unspliced transcript, that is exons + introns * *gene_exon_intron* gives the exons + introns of a gene * *coding* gives the coding sequence only * *coding_transcript_flank* gives the flanking region of the transcript including the UTRs, this must be accompanied with a given value for the upstream or downstream attribute * *coding_gene_flank* gives the flanking region of the gene including the UTRs, this must be accompanied with a given value for the upstream or downstream attribute * *transcript_flank* gives the flanking region of the transcript exculding the UTRs, this must be accompanied with a given value for the upstream or downstream attribute * *gene_flank* gives the flanking region of the gene excluding the UTRs, this must be accompanied with a given value for the upstream or downstream attribute In MySQL mode the `getSequence()` function is more limited and the sequence that is returned is the 5' to 3'+ strand of the genomic sequence, given a chromosome, as start and an end position. This task requires us to retrieve 100bp upstream promoter sequences from a set of EntrzGene identifiers. The *type* argument in `getSequence()` can be thought of as the filter in this query and uses the same input names given by `listFilters()`. In our query we use entrezgene for the type argument. Next we have to specify which type of sequences we want to retrieve, here we are interested in the sequences of the promoter region, starting right next to the coding start of the gene. Setting the *seqType* to coding_gene_flank will give us what we need. The *upstream* argument is used to specify how many bp of upstream sequence we want to retrieve, here we'll retrieve a rather short sequence of 100bp. Putting this all together in `getSequence()` gives: ```{r task7, eval=TRUE} entrez=c("673","7157","837") getSequence(id = entrez, type="entrezgene", seqType="coding_gene_flank", upstream=100, mart=ensembl) ``` ## Retrieve all 5' UTR sequences of all genes that are located on chromosome 3 between the positions 185,514,033 and 185,535,839 As described in the provious task getSequence can also use chromosomal coordinates to retrieve sequences of all genes that lie in the given region. We also have to specify which type of identifier we want to retrieve together with the sequences, here we choose for entrezgene identifiers. ```{r task8, echo=TRUE,eval=TRUE} utr5 = getSequence(chromosome=3, start=185514033, end=185535839, type="entrezgene", seqType="5utr", mart=ensembl) utr5 ``` ## Retrieve protein sequences for a given list of EntrezGene identifiers In this task the type argument specifies which type of identifiers we are using. To get an overview of other valid identifier types we refer to the `listFilters()` function. ```{r task9, echo=TRUE, eval=TRUE} protein = getSequence(id=c(100, 5728), type="entrezgene", seqType="peptide", mart=ensembl) protein ``` ## Retrieve known SNPs located on the human chromosome 8 between positions 148350 and 148612 For this example we'll first have to connect to a different BioMart database, namely snp. ```{r task10, echo=TRUE, eval=TRUE} snpmart = useMart(biomart = "ENSEMBL_MART_SNP", dataset="hsapiens_snp") ``` The `listAttributes()` and `listFilters()` functions give us an overview of the available attributes and filters. From these we need: *refsnp_id*, *allele*, *chrom_start* and *chrom_strand* as attributes; and as filters we'll use: *chrom_start*, *chrom_end* and *chr_name*. Note that when a chromosome name, a start position and an end position are jointly used as filters, the BioMart webservice interprets this as return everything from the given chromosome between the given start and end positions. Putting our selected attributes and filters into getBM gives: ```{r task10b} getBM(attributes = c('refsnp_id','allele','chrom_start','chrom_strand'), filters = c('chr_name','start','end'), values = list(8,148350,148612), mart = snpmart) ``` ## Given the human gene TP53, retrieve the human chromosomal location of this gene and also retrieve the chromosomal location and RefSeq id of its homolog in mouse. The `getLDS()` (Get Linked Dataset) function provides functionality to link 2 BioMart datasets which each other and construct a query over the two datasets. In Ensembl, linking two datasets translates to retrieving homology data across species. The usage of getLDS is very similar to `getBM()`. The linked dataset is provided by a separate `Mart` object and one has to specify filters and attributes for the linked dataset. Filters can either be applied to both datasets or to one of the datasets. Use the listFilters and listAttributes functions on both `Mart` objects to find the filters and attributes for each dataset (species in Ensembl). The attributes and filters of the linked dataset can be specified with the attributesL and filtersL arguments. Entering all this information into `getLDS()` gives: ```{r getLDS} human = useMart("ensembl", dataset = "hsapiens_gene_ensembl") mouse = useMart("ensembl", dataset = "mmusculus_gene_ensembl") getLDS(attributes = c("hgnc_symbol","chromosome_name", "start_position"), filters = "hgnc_symbol", values = "TP53",mart = human, attributesL = c("refseq_mrna","chromosome_name","start_position"), martL = mouse) ``` # Using archived versions of Ensembl It is possible to query archived versions of Ensembl through `r Biocpkg("biomaRt")`. There are currently two ways to access archived versions. ## Using `archive = TRUE` First we list the available Ensembl archives by using the `listMarts()` function and setting the archive attribute to TRUE. Note that not all archives are available this way and it seems that recently this only gives access to few archives if you don't see the version of the archive you need please look at the 2nd way to access archives. ```{r archiveMarts1} listMarts(archive = TRUE) ``` Next we select the archive we want to use using the `useMart()` function, again setting the archive attribute to TRUE and giving the full name of the BioMart e.g. ensembl_mart_46. ```{r archiveMarts2, echo = TRUE, eval = TRUE} ensembl = useMart("ensembl_mart_46", dataset="hsapiens_gene_ensembl", archive = TRUE) ``` If you don't know the dataset you want to use could first connect to the BioMart using `useMart()` and then use the `listDatasets()` function on this object. After you selected the BioMart database and dataset, queries can be performed in the same way as when using the current BioMart versions. ## Accessing archives through specifying the archive host Use the website and go down the bottom of the page. Click on 'view in Archive' and select the archive you need. Copy the url and use that url as shown below to connect to the specified BioMart database. The example below shows how to query Ensembl 54. ```{r archiveMarts3, echo = TRUE, eval = TRUE} listMarts(host='may2009.archive.ensembl.org') ensembl54=useMart(host='may2009.archive.ensembl.org', biomart='ENSEMBL_MART_ENSEMBL') ensembl54=useMart(host='may2009.archive.ensembl.org', biomart='ENSEMBL_MART_ENSEMBL', dataset='hsapiens_gene_ensembl') ``` # Using a BioMart other than Ensembl To demonstrate the use of the `r Biocpkg("biomaRt")` package with non-Ensembl databases the next query is performed using the Wormbase ParaSite BioMart. In this example, we use the `listMarts()` function to find the name of the available marts, given the URL of Wormbase. We use this to connect to Wormbase BioMart, find and select the gene dataset, and print the first 6 available attributes and filters. Then we use a list of gene names as filter and retrieve associated transcript IDs and the transcript biotype. ```{r wormbase, echo=TRUE, eval=TRUE} listMarts(host = "parasite.wormbase.org") wormbase = useMart(biomart = "parasite_mart", host = "parasite.wormbase.org") listDatasets(wormbase) wormbase <- useDataset(mart = wormbase, dataset = "wbps_gene") head(listFilters(wormbase)) head(listAttributes(wormbase)) getBM(attributes = c("external_gene_id","ensembl_transcript_id","transcript_biotype"), filters="gene_name", values=c("unc-26","his-33"), mart=wormbase) ``` # biomaRt helper functions This section describes a set of `r Biocpkg("biomaRt")` helper functions that can be used to export FASTA format sequences, retrieve values for certain filters and exploring the available filters and attributes in a more systematic manner. ## exportFASTA The data.frames obtained by the getSequence function can be exported to FASTA files using the `exportFASTA()` function. One has to specify the data.frame to export and the filename using the file argument. ## Finding out more information on filters ### filterType Boolean filters need a value TRUE or FALSE in `r Biocpkg("biomaRt")`. Setting the value TRUE will include all information that fulfill the filter requirement. Setting FALSE will exclude the information that fulfills the filter requirement and will return all values that don't fulfill the filter. For most of the filters, their name indicates if the type is a boolean or not and they will usually start with "with". However this is not a rule and to make sure you got the type right you can use the function `filterType()` to investigate the type of the filter you want to use. ```{r filterType} filterType("with_affy_hg_u133_plus_2",ensembl) ``` ### filterOptions Some filters have a limited set of values that can be given to them. To know which values these are one can use the `filterOptions()` function to retrieve the predetermed values of the respective filter. ```{r filterOptions} filterOptions("biotype",ensembl) ``` If there are no predetermed values e.g. for the entrezgene filter, then `filterOptions()` will return the type of filter it is. And most of the times the filter name or it's description will suggest what values one case use for the respective filter (e.g. entrezgene filter will work with enterzgene identifiers as values) ## Attribute Pages For large BioMart databases such as Ensembl, the number of attributes displayed by the `listAttributes()` function can be very large. In BioMart databases, attributes are put together in pages, such as sequences, features, homologs for Ensembl. An overview of the attributes pages present in the respective BioMart dataset can be obtained with the `attributePages()` function. ```{r attributePages} pages = attributePages(ensembl) pages ``` To show us a smaller list of attributes which belong to a specific page, we can now specify this in the `listAttributes()` function. *The set of attributes is still quite long, so we use `head()` to show only the first few items here.* ```{r listAttributes} head(listAttributes(ensembl, page="feature_page")) ``` We now get a short list of attributes related to the region where the genes are located. # Local BioMart databases The `r Biocpkg("biomaRt")` package can be used with a local install of a public BioMart database or a locally developed BioMart database and web service. In order for `r Biocpkg("biomaRt")` to recognize the database as a BioMart, make sure that the local database you create has a name conform with ` database_mart_version ` where database is the name of the database and version is a version number. No more underscores than the ones showed should be present in this name. A possible name is for example ` ensemblLocal_mart_46 `. ## Minimum requirements for local database installation More information on installing a local copy of a BioMart database or develop your own BioMart database and webservice can be found on Once the local database is installed you can use `r Biocpkg("biomaRt")` on this database by: ```{r localCopy, eval = FALSE} listMarts(host="www.myLocalHost.org", path="/myPathToWebservice/martservice") mart=useMart("nameOfMyMart",dataset="nameOfMyDataset",host="www.myLocalHost.org", path="/myPathToWebservice/martservice") ``` For more information on how to install a public BioMart database see: http://www.biomart.org/install.html and follow link databases. # Using `select()` In order to provide a more consistent interface to all annotations in Bioconductor the `select()`, `columns()`, `keytypes()` and `keys()` have been implemented to wrap some of the existing functionality above. These methods can be called in the same manner that they are used in other parts of the project except that instead of taking a `AnnotationDb` derived class they take instead a `Mart` derived class as their 1st argument. Otherwise usage should be essentially the same. You still use `columns()` to discover things that can be extracted from a `Mart`, and `keytypes()` to discover which things can be used as keys with `select()`. ```{r columnsAndKeyTypes} mart <- useMart(dataset="hsapiens_gene_ensembl",biomart='ensembl') head(keytypes(mart), n=3) head(columns(mart), n=3) ``` And you still can use `keys()` to extract potential keys, for a particular key type. ```{r keys1} k = keys(mart, keytype="chromosome_name") head(k, n=3) ``` When using `keys()`, you can even take advantage of the extra arguments that are available for others keys methods. ```{r keys2} k = keys(mart, keytype="chromosome_name", pattern="LRG") head(k, n=3) ``` Unfortunately the `keys()` method will not work with all key types because they are not all supported. But you can still use `select()` here to extract columns of data that match a particular set of keys (this is basically a wrapper for `getBM()`). ```{r select} affy=c("202763_at","209310_s_at","207500_at") select(mart, keys=affy, columns=c('affy_hg_u133_plus_2','entrezgene'), keytype='affy_hg_u133_plus_2') ``` So why would we want to do this when we already have functions like `getBM()`? For two reasons: 1) for people who are familiar with select and it's helper methods, they can now proceed to use `r Biocpkg("biomaRt")` making the same kinds of calls that are already familiar to them and 2) because the select method is implemented in many places elsewhere, the fact that these methods are shared allows for more convenient programmatic access of all these resources. An example of a package that takes advantage of this is the `r Biocpkg("OrganismDbi")` package. Where several packages can be accessed as if they were one resource. # Session Info ```{r sessionInfo} sessionInfo() warnings() ``` biomaRt/inst/doc/biomaRt.html0000644000175400017540000034527113001246365017216 0ustar00biocbuildbiocbuild The biomaRt users guide

Package version: biomaRt 2.30.0

Contents

1 Introduction

In recent years a wealth of biological data has become available in public data repositories. Easy access to these valuable data resources and firm integration with data analysis is needed for comprehensive bioinformatics data analysis. The biomaRt package, provides an interface to a growing collection of databases implementing the BioMart software suite. The package enables retrieval of large amounts of data in a uniform way without the need to know the underlying database schemas or write complex SQL queries. Examples of BioMart databases are Ensembl, Uniprot and HapMap. These major databases give biomaRt users direct access to a diverse set of data and enable a wide range of powerful online queries from R.

2 Selecting a BioMart database and dataset

Every analysis with biomaRt starts with selecting a BioMart database to use. A first step is to check which BioMart web services are available. The function listMarts() will display all available BioMart web services

library("biomaRt")
listMarts()
##                biomart               version
## 1 ENSEMBL_MART_ENSEMBL      Ensembl Genes 86
## 2   ENSEMBL_MART_MOUSE      Mouse strains 86
## 3     ENSEMBL_MART_SNP  Ensembl Variation 86
## 4 ENSEMBL_MART_FUNCGEN Ensembl Regulation 86
## 5    ENSEMBL_MART_VEGA               Vega 66

Note: if the function useMart() runs into proxy problems you should set your proxy first before calling any biomaRt functions.
You can do this using the Sys.putenv command:

Sys.setenv("http_proxy" = "http://my.proxy.org:9999")

Some users have reported that the workaround above does not work, in this case an alternative proxy solution below can be tried:

options(RCurlOptions = list(proxy="uscache.kcc.com:80",proxyuserpwd="------:-------"))

The useMart() function can now be used to connect to a specified BioMart database, this must be a valid name given by listMarts(). In the next example we choose to query the Ensembl BioMart database.

ensembl=useMart("ensembl")

BioMart databases can contain several datasets, for Ensembl every species is a different dataset. In a next step we look at which datasets are available in the selected BioMart by using the function listDatasets().

listDatasets(ensembl)
##                           dataset                                description           version
## 1          oanatinus_gene_ensembl     Ornithorhynchus anatinus genes (OANA5)             OANA5
## 2         cporcellus_gene_ensembl            Cavia porcellus genes (cavPor3)           cavPor3
## 3         gaculeatus_gene_ensembl     Gasterosteus aculeatus genes (BROADS1)           BROADS1
## 4  itridecemlineatus_gene_ensembl Ictidomys tridecemlineatus genes (spetri2)           spetri2
## 5          lafricana_gene_ensembl         Loxodonta africana genes (loxAfr3)           loxAfr3
## 6         choffmanni_gene_ensembl        Choloepus hoffmanni genes (choHof1)           choHof1
## 7          csavignyi_gene_ensembl             Ciona savignyi genes (CSAV2.0)           CSAV2.0
## 8             fcatus_gene_ensembl        Felis catus genes (Felis_catus_6.2)   Felis_catus_6.2
## 9        rnorvegicus_gene_ensembl         Rattus norvegicus genes (Rnor_6.0)          Rnor_6.0
## 10         psinensis_gene_ensembl     Pelodiscus sinensis genes (PelSin_1.0)        PelSin_1.0
## 11          cjacchus_gene_ensembl  Callithrix jacchus genes (C_jacchus3.2.1)    C_jacchus3.2.1
## 12        ttruncatus_gene_ensembl         Tursiops truncatus genes (turTru1)           turTru1
## 13       scerevisiae_gene_ensembl   Saccharomyces cerevisiae genes (R64-1-1)           R64-1-1
## 14          celegans_gene_ensembl    Caenorhabditis elegans genes (WBcel235)          WBcel235
## 15          csabaeus_gene_ensembl      Chlorocebus sabaeus genes (ChlSab1.1)         ChlSab1.1
## 16        oniloticus_gene_ensembl    Oreochromis niloticus genes (Orenil1.0)         Orenil1.0
## 17        amexicanus_gene_ensembl       Astyanax mexicanus genes (AstMex102)         AstMex102
## 18         trubripes_gene_ensembl            Takifugu rubripes genes (FUGU4)             FUGU4
## 19          pmarinus_gene_ensembl    Petromyzon marinus genes (Pmarinus_7.0)      Pmarinus_7.0
## 20        eeuropaeus_gene_ensembl       Erinaceus europaeus genes (HEDGEHOG)          HEDGEHOG
## 21       falbicollis_gene_ensembl     Ficedula albicollis genes (FicAlb_1.4)        FicAlb_1.4
## 22         etelfairi_gene_ensembl           Echinops telfairi genes (TENREC)            TENREC
## 23     cintestinalis_gene_ensembl              Ciona intestinalis genes (KH)                KH
## 24      ptroglodytes_gene_ensembl         Pan troglodytes genes (CHIMP2.1.4)        CHIMP2.1.4
## 25       nleucogenys_gene_ensembl        Nomascus leucogenys genes (Nleu1.0)           Nleu1.0
## 26           sscrofa_gene_ensembl             Sus scrofa genes (Sscrofa10.2)       Sscrofa10.2
## 27        ocuniculus_gene_ensembl    Oryctolagus cuniculus genes (OryCun2.0)         OryCun2.0
## 28     dnovemcinctus_gene_ensembl     Dasypus novemcinctus genes (Dasnov3.0)         Dasnov3.0
## 29         pcapensis_gene_ensembl          Procavia capensis genes (proCap1)           proCap1
## 30          tguttata_gene_ensembl    Taeniopygia guttata genes (taeGut3.2.4)       taeGut3.2.4
## 31        mlucifugus_gene_ensembl         Myotis lucifugus genes (Myoluc2.0)         Myoluc2.0
## 32          hsapiens_gene_ensembl             Homo sapiens genes (GRCh38.p7)         GRCh38.p7
## 33          pformosa_gene_ensembl      Poecilia formosa genes (PoeFor_5.1.2)      PoeFor_5.1.2
## 34        tbelangeri_gene_ensembl         Tupaia belangeri genes (TREESHREW)         TREESHREW
## 35             mfuro_gene_ensembl Mustela putorius furo genes (MusPutFur1.0)      MusPutFur1.0
## 36           ggallus_gene_ensembl    Gallus gallus genes (Gallus_gallus-5.0) Gallus_gallus-5.0
## 37       xtropicalis_gene_ensembl         Xenopus tropicalis genes (JGI_4.2)           JGI_4.2
## 38         ecaballus_gene_ensembl             Equus caballus genes (EquCab2)           EquCab2
## 39           pabelii_gene_ensembl                 Pongo abelii genes (PPYG2)             PPYG2
## 40            drerio_gene_ensembl                 Danio rerio genes (GRCz10)            GRCz10
## 41        xmaculatus_gene_ensembl  Xiphophorus maculatus genes (Xipmac4.4.2)       Xipmac4.4.2
## 42     tnigroviridis_gene_ensembl  Tetraodon nigroviridis genes (TETRAODON8)        TETRAODON8
## 43        lchalumnae_gene_ensembl        Latimeria chalumnae genes (LatCha1)           LatCha1
## 44      amelanoleuca_gene_ensembl     Ailuropoda melanoleuca genes (ailMel1)           ailMel1
## 45          mmulatta_gene_ensembl          Macaca mulatta genes (Mmul_8.0.1)        Mmul_8.0.1
## 46         pvampyrus_gene_ensembl          Pteropus vampyrus genes (pteVam1)           pteVam1
## 47           panubis_gene_ensembl             Papio anubis genes (PapAnu2.0)         PapAnu2.0
## 48        mdomestica_gene_ensembl      Monodelphis domestica genes (BROADO5)           BROADO5
## 49     acarolinensis_gene_ensembl      Anolis carolinensis genes (AnoCar2.0)         AnoCar2.0
## 50            vpacos_gene_ensembl              Vicugna pacos genes (vicPac1)           vicPac1
## 51         tsyrichta_gene_ensembl           Tarsius syrichta genes (tarSyr1)           tarSyr1
## 52        ogarnettii_gene_ensembl         Otolemur garnettii genes (OtoGar3)           OtoGar3
## 53     dmelanogaster_gene_ensembl      Drosophila melanogaster genes (BDGP6)             BDGP6
## 54          mmurinus_gene_ensembl        Microcebus murinus genes (Mmur_2.0)          Mmur_2.0
## 55         loculatus_gene_ensembl       Lepisosteus oculatus genes (LepOcu1)           LepOcu1
## 56          olatipes_gene_ensembl            Oryzias latipes genes (MEDAKA1)           MEDAKA1
## 57         oprinceps_gene_ensembl             Ochotona princeps genes (pika)              pika
## 58          ggorilla_gene_ensembl          Gorilla gorilla genes (gorGor3.1)         gorGor3.1
## 59            dordii_gene_ensembl            Dipodomys ordii genes (dipOrd1)           dipOrd1
## 60            oaries_gene_ensembl                Ovis aries genes (Oar_v3.1)          Oar_v3.1
## 61         mmusculus_gene_ensembl             Mus musculus genes (GRCm38.p4)         GRCm38.p4
## 62        mgallopavo_gene_ensembl           Meleagris gallopavo genes (UMD2)              UMD2
## 63           gmorhua_gene_ensembl               Gadus morhua genes (gadMor1)           gadMor1
## 64          saraneus_gene_ensembl        Sorex araneus genes (COMMON_SHREW1)     COMMON_SHREW1
## 65    aplatyrhynchos_gene_ensembl    Anas platyrhynchos genes (BGI_duck_1.0)      BGI_duck_1.0
## 66         sharrisii_gene_ensembl      Sarcophilus harrisii genes (DEVIL7.0)          DEVIL7.0
## 67          meugenii_gene_ensembl          Macropus eugenii genes (Meug_1.0)          Meug_1.0
## 68           btaurus_gene_ensembl                  Bos taurus genes (UMD3.1)            UMD3.1
## 69       cfamiliaris_gene_ensembl         Canis familiaris genes (CanFam3.1)         CanFam3.1

To select a dataset we can update the Mart object using the function useDataset(). In the example below we choose to use the hsapiens dataset.

ensembl = useDataset("hsapiens_gene_ensembl",mart=ensembl)

Or alternatively if the dataset one wants to use is known in advance, we can select a BioMart database and dataset in one step by:

ensembl = useMart("ensembl",dataset="hsapiens_gene_ensembl")

3 How to build a biomaRt query

The getBM() function has three arguments that need to be introduced: filters, attributes and values. Filters define a restriction on the query. For example you want to restrict the output to all genes located on the human X chromosome then the filter chromosome_name can be used with value ‘X’. The listFilters() function shows you all available filters in the selected dataset.

filters = listFilters(ensembl)
filters[1:5,]
##              name     description
## 1 chromosome_name Chromosome name
## 2           start Gene Start (bp)
## 3             end   Gene End (bp)
## 4      band_start      Band Start
## 5        band_end        Band End

Attributes define the values we are interested in to retrieve. For example we want to retrieve the gene symbols or chromosomal coordinates. The listAttributes() function displays all available attributes in the selected dataset.

attributes = listAttributes(ensembl)
attributes[1:5,]
##                    name           description         page
## 1       ensembl_gene_id       Ensembl Gene ID feature_page
## 2 ensembl_transcript_id Ensembl Transcript ID feature_page
## 3    ensembl_peptide_id    Ensembl Protein ID feature_page
## 4       ensembl_exon_id       Ensembl Exon ID feature_page
## 5           description           Description feature_page

The getBM() function is the main query function in biomaRt. It has four main arguments:

  • attributes: is a vector of attributes that one wants to retrieve (= the output of the query).
  • filters: is a vector of filters that one wil use as input to the query.
  • values: a vector of values for the filters. In case multple filters are in use, the values argument requires a list of values where each position in the list corresponds to the position of the filters in the filters argument (see examples below).
  • mart: is an object of class Mart, which is created by the useMart() function.

Note: for some frequently used queries to Ensembl, wrapper functions are available: getGene() and getSequence(). These functions call the getBM() function with hard coded filter and attribute names.

Now that we selected a BioMart database and dataset, and know about attributes, filters, and the values for filters; we can build a biomaRt query. Let’s make an easy query for the following problem: We have a list of Affymetrix identifiers from the u133plus2 platform and we want to retrieve the corresponding EntrezGene identifiers using the Ensembl mappings.

The u133plus2 platform will be the filter for this query and as values for this filter we use our list of Affymetrix identifiers. As output (attributes) for the query we want to retrieve the EntrezGene and u133plus2 identifiers so we get a mapping of these two identifiers as a result. The exact names that we will have to use to specify the attributes and filters can be retrieved with the listAttributes() and listFilters() function respectively. Let’s now run the query:

affyids=c("202763_at","209310_s_at","207500_at")
getBM(attributes=c('affy_hg_u133_plus_2', 'entrezgene'), 
      filters = 'affy_hg_u133_plus_2', 
      values = affyids, 
      mart = ensembl)
##   affy_hg_u133_plus_2 entrezgene
## 1           207500_at        838
## 2           202763_at        836
## 3         209310_s_at        837

4 Examples of biomaRt queries

In the sections below a variety of example queries are described. Every example is written as a task, and we have to come up with a biomaRt solution to the problem.

4.1 Annotate a set of Affymetrix identifiers with HUGO symbol and chromosomal locations of corresponding genes

We have a list of Affymetrix hgu133plus2 identifiers and we would like to retrieve the HUGO gene symbols, chromosome names, start and end positions and the bands of the corresponding genes. The listAttributes() and the listFilters() functions give us an overview of the available attributes and filters and we look in those lists to find the corresponding attribute and filter names we need. For this query we’ll need the following attributes: hgnc_symbol, chromsome_name, start_position, end_position, band and affy_hg_u133_plus_2 (as we want these in the output to provide a mapping with our original Affymetrix input identifiers. There is one filter in this query which is the affy_hg_u133_plus_2 filter as we use a list of Affymetrix identifiers as input. Putting this all together in the getBM() and performing the query gives:

affyids=c("202763_at","209310_s_at","207500_at")
getBM(attributes = c('affy_hg_u133_plus_2', 'hgnc_symbol', 'chromosome_name',
                   'start_position', 'end_position', 'band'),
      filters = 'affy_hg_u133_plus_2', 
      values = affyids, 
      mart = ensembl)
##   affy_hg_u133_plus_2 hgnc_symbol chromosome_name start_position end_position  band
## 1           207500_at       CASP5              11      104994235    105023168 q22.3
## 2           202763_at       CASP3               4      184627696    184649509 q35.1
## 3         209310_s_at       CASP4              11      104942866    104969436 q22.3

4.2 Annotate a set of EntrezGene identifiers with GO annotation

In this task we start out with a list of EntrezGene identiers and we want to retrieve GO identifiers related to biological processes that are associated with these entrezgene identifiers. Again we look at the output of listAttributes() and listFilters() to find the filter and attributes we need. Then we construct the following query:

entrez=c("673","837")
goids = getBM(attributes = c('entrezgene', 'go_id'), 
              filters = 'entrezgene', 
              values = entrez, 
              mart = ensembl)
head(goids)
##   entrezgene      go_id
## 1        673           
## 2        673 GO:0015758
## 3        673 GO:0071277
## 4        673 GO:0090150
## 5        673 GO:0009887
## 6        673 GO:0070374

4.3 Retrieve all HUGO gene symbols of genes that are located on chromosomes 17,20 or Y, and are associated with specific GO terms

The GO terms we are interested in are: GO:0051330, GO:0000080, GO:0000114, GO:0000082. The key to performing this query is to understand that the getBM() function enables you to use more than one filter at the same time. In order to do this, the filter argument should be a vector with the filter names. The values should be a list, where the first element of the list corresponds to the first filter and the second list element to the second filter and so on. The elements of this list are vectors containing the possible values for the corresponding filters.

 go=c("GO:0051330","GO:0000080","GO:0000114","GO:0000082")
 chrom=c(17,20,"Y")
 getBM(attributes= "hgnc_symbol",
        filters=c("go_id","chromosome_name"),
        values=list(go, chrom), mart=ensembl)
##   hgnc_symbol
## 1        CDC6
## 2        CDK3
## 3        PCNA
## 4       CRLF3
## 5        RPA1
## 6        MCM8
## 7     RPS6KB1

4.4 Annotate set of idenfiers with INTERPRO protein domain identifiers

In this example we want to annotate the following two RefSeq identifiers: NM_005359 and NM_000546 with INTERPRO protein domain identifiers and a description of the protein domains.

refseqids = c("NM_005359","NM_000546")
ipro = getBM(attributes=c("refseq_mrna","interpro","interpro_description"), 
             filters="refseq_mrna",
             values=refseqids, 
             mart=ensembl)
ipro
##    refseq_mrna  interpro                                   interpro_description
## 1    NM_000546 IPR002117                           p53 tumour suppressor family
## 2    NM_000546 IPR008967             p53-like transcription factor, DNA-binding
## 3    NM_000546 IPR010991                            p53, tetramerisation domain
## 4    NM_000546 IPR011615                                p53, DNA-binding domain
## 5    NM_000546 IPR012346 p53/RUNT-type transcription factor, DNA-binding domain
## 6    NM_000546 IPR013872                             p53 transactivation domain
## 7    NM_005359 IPR001132                              SMAD domain, Dwarfin-type
## 8    NM_005359 IPR003619                           MAD homology 1, Dwarfin-type
## 9    NM_005359 IPR008984                                        SMAD/FHA domain
## 10   NM_005359 IPR013019                                      MAD homology, MH1
## 11   NM_005359 IPR013790                                                Dwarfin
## 12   NM_005359 IPR017855                                       SMAD domain-like

4.5 Select all Affymetrix identifiers on the hgu133plus2 chip and Ensembl gene identifiers for genes located on chromosome 16 between basepair 1100000 and 1250000.

In this example we will again use multiple filters: chromosome_name, start, and end as we filter on these three conditions. Note that when a chromosome name, a start position and an end position are jointly used as filters, the BioMart webservice interprets this as return everything from the given chromosome between the given start and end positions.

getBM(attributes = c('affy_hg_u133_plus_2','ensembl_gene_id'), 
      filters = c('chromosome_name','start','end'),
      values = list(16,1100000,1250000), 
      mart = ensembl)
##    affy_hg_u133_plus_2 ensembl_gene_id
## 1                      ENSG00000260702
## 2            215502_at ENSG00000260532
## 3                      ENSG00000273551
## 4            205845_at ENSG00000196557
## 5                      ENSG00000196557
## 6                      ENSG00000260403
## 7                      ENSG00000259910
## 8                      ENSG00000261294
## 9          220339_s_at ENSG00000116176
## 10                     ENSG00000277010
## 11         217023_x_at ENSG00000197253
## 12         210084_x_at ENSG00000197253
## 13         215382_x_at ENSG00000197253
## 14         216474_x_at ENSG00000197253
## 15         207134_x_at ENSG00000197253
## 16         205683_x_at ENSG00000197253
## 17         217023_x_at ENSG00000172236
## 18         210084_x_at ENSG00000172236
## 19         215382_x_at ENSG00000172236
## 20         207741_x_at ENSG00000172236
## 21         216474_x_at ENSG00000172236
## 22         207134_x_at ENSG00000172236
## 23         205683_x_at ENSG00000172236

4.6 Retrieve all entrezgene identifiers and HUGO gene symbols of genes which have a “MAP kinase activity” GO term associated with it.

The GO identifier for MAP kinase activity is GO:0004707. In our query we will use go_id as our filter, and entrezgene and hgnc_symbol as attributes. Here’s the query:

getBM(attributes = c('entrezgene','hgnc_symbol'), 
      filters = 'go_id', 
      values = 'GO:0004707', 
      mart = ensembl)
##    entrezgene hgnc_symbol
## 1      225689      MAPK15
## 2       51701         NLK
## 3        5594       MAPK1
## 4        5597       MAPK6
## 5        6300      MAPK12
## 6        5600      MAPK11
## 7        5603      MAPK13
## 8        1432      MAPK14
## 9        5596       MAPK4
## 10       5598       MAPK7
## 11       5595       MAPK3

4.7 Given a set of EntrezGene identifiers, retrieve 100bp upstream promoter sequences

All sequence related queries to Ensembl are available through the getSequence() wrapper function. getBM() can also be used directly to retrieve sequences but this can get complicated so using getSequence is recommended.

Sequences can be retrieved using the getSequence() function either starting from chromosomal coordinates or identifiers.
The chromosome name can be specified using the chromosome argument. The start and end arguments are used to specify start and end positions on the chromosome. The type of sequence returned can be specified by the seqType argument which takes the following values:

  • cdna
  • peptide for protein sequences
  • 3utr for 3’ UTR sequences
  • 5utr for 5’ UTR sequences
  • gene_exon for exon sequences only
  • transcript_exon for transcript specific exonic sequences only
  • transcript_exon_intron gives the full unspliced transcript, that is exons + introns
  • gene_exon_intron gives the exons + introns of a gene
  • coding gives the coding sequence only
  • coding_transcript_flank gives the flanking region of the transcript including the UTRs, this must be accompanied with a given value for the upstream or downstream attribute
  • coding_gene_flank gives the flanking region of the gene including the UTRs, this must be accompanied with a given value for the upstream or downstream attribute
  • transcript_flank gives the flanking region of the transcript exculding the UTRs, this must be accompanied with a given value for the upstream or downstream attribute
  • gene_flank gives the flanking region of the gene excluding the UTRs, this must be accompanied with a given value for the upstream or downstream attribute

In MySQL mode the getSequence() function is more limited and the sequence that is returned is the 5’ to 3’+ strand of the genomic sequence, given a chromosome, as start and an end position.

This task requires us to retrieve 100bp upstream promoter sequences from a set of EntrzGene identifiers. The type argument in getSequence() can be thought of as the filter in this query and uses the same input names given by listFilters(). In our query we use entrezgene for the type argument. Next we have to specify which type of sequences we want to retrieve, here we are interested in the sequences of the promoter region, starting right next to the coding start of the gene. Setting the seqType to coding_gene_flank will give us what we need. The upstream argument is used to specify how many bp of upstream sequence we want to retrieve, here we’ll retrieve a rather short sequence of 100bp. Putting this all together in getSequence() gives:

entrez=c("673","7157","837")
getSequence(id = entrez, 
            type="entrezgene",
            seqType="coding_gene_flank",
            upstream=100, 
            mart=ensembl) 
##                                                                                      coding_gene_flank entrezgene
## 1 CCTCCGCCTCCGCCTCCGCCTCCGCCTCCCCCAGCTCTCCGCCTCCCTTCCCCCTCCCCGCCCGACAGCGGCCGCTCGGGCCCCGGCTCTCGGTTATAAG        673
## 2 CACGTTTCCGCCCTTTGCAATAAGGAAATACATAGTTTACTTTCATTTTTGACTCTGAGGCTCTTTCCAACGCTGTAAAAAAGGACAGAGGCTGTTCCCT        837
## 3 TCCTTCTCTGCAGGCCCAGGTGACCCAGGGTTGGAAGTGTCTCATGCTGGATCCCCACTTTTCCTCTTGCAGCAGCCAGACTGCCTTCCGGGTCACTGCC       7157

4.8 Retrieve all 5’ UTR sequences of all genes that are located on chromosome 3 between the positions 185,514,033 and 185,535,839

As described in the provious task getSequence can also use chromosomal coordinates to retrieve sequences of all genes that lie in the given region. We also have to specify which type of identifier we want to retrieve together with the sequences, here we choose for entrezgene identifiers.

utr5 = getSequence(chromosome=3, start=185514033, end=185535839,
                   type="entrezgene",
                   seqType="5utr", 
                   mart=ensembl)
utr5
##                                                                                                                                             5utr
## 1                                                                                                                           Sequence unavailable
## 2                                                                                                        ATTCTTGTGAATGTGACACACGATCTCTCCAGTTTCCAT
## 3                                                        TGAGCAAAATCCCACAGTGGAAACTCTTAAGCCTCTGCGAAGTAAATCATTCTTGTGAATGTGACACACGATCTCTCCAGTTTCCAT
## 4 AGTCCCTAGGGAACTTCCTGTTGTCACCACACCTCTGAGTCGTCTGAGCTCACTGTGAGCAAAATCCCACAGTGGAAACTCTTAAGCCTCTGCGAAGTAAATCATTCTTGTGAATGTGACACACGATCTCTCCAGTTTCCAT
##   entrezgene
## 1     200879
## 2     200879
## 3     200879
## 4     200879

4.9 Retrieve protein sequences for a given list of EntrezGene identifiers

In this task the type argument specifies which type of identifiers we are using. To get an overview of other valid identifier types we refer to the listFilters() function.

protein = getSequence(id=c(100, 5728),
                      type="entrezgene",
                      seqType="peptide", 
                      mart=ensembl)
protein
##                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              peptide
## 1                                                                                                                                                                                                                                                                                                                           MAQTPAFDKPKVELHVHLDGSIKPETILYYGRRRGIALPANTAEGLLNVIGMDKPLTLPDFLAKFDYYMPAIAGCREAIKRIAYEFVEMKAKEGVVYVEVRYSPHLLANSKVEPIPWNQAEGDLTPDEVVALVGQGLQEGERDFGVKARSILCCMRHQPNWSPKVVELCKKYQQQTVVAIDLAGDETIPGSSLLPGHVQAYQEAVKSGIHRTVHAGEVGSAEVVKEAVDILKTERLGHGYHTLEDQALYNRLRQENMHFEAQK*
## 2                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       MAQTPAFDKPKVELHVHLDGSIKPETILYYGRRRGIALPANTAEGLLNVIGMDKPLTLPDFLAKFDYYMPAIARL*
## 3                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               Sequence unavailable
## 4                                                                                                                                                                                                                                                                                                                                                                                                                                         ALLFHKMMFETIPMFSGGTCNPQFVVCQLKVKIYSSNSGPTRREDKFMYFEFPQPLPVCGDIKVEFFHKQNKMLKKDKMFHFWVNTFFIPGPEETSEKVENGSLCDQEIDSICSIERADNDKEYLVLTLTKNDLDKANKDKANRYFSPNFKVS*
## 5                                                                                                                                                                                                                       MAQTPAFDKPKVELHVHLDGSIKPETILYYGRRRGIALPANTAEGLLNVIGMDKPLTLPDFLAKFDYYMPAIAGCREAIKRIAYEFVEMKAKEGVVYVEVRYSPHLLANSKVEPIPWNQAEGDLTPDEVVALVGQGLQEGERDFGVKARSILCCMRHQPNWSPKVVELCKKYQQQTVVAIDLAGDETIPGSSLLPGHVQAYQEAVKSGIHRTVHAGEVGSAEVVKEAVDILKTERLGHGYHTLEDQALYNRLRQENMHFEICPWSSYLTGAWKPDTEHAVIRLKNDQANYSLNTDDPLIFKSTLDTDYQMTKRDMGFTEEEFKRLNINAAKSSFLPEDEKRELLDLLYKAYGMPPSASAGQNL*
## 6                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               Sequence unavailable
## 7  LERGGEAAAAAAAAAAAPGRGSESPVTISRAGNAGELVSPLLLPPTRRRRRRHIQGPGPVLNLPSAAAAPPVARAPEAAGGGSRSEDYSSSPHSAAAAARPLAAEEKQAQSLQPSSSRRSSHYPAAVQSQAAAERGASATAKSRAISILQKKPRHQQLLPSLSSFFFSHRLPDMTAIIKEIVSRNKRRYQEDGFDLDLTYIYPNIIAMGFPAERLEGVYRNNIDDVVRFLDSKHKNHYKIYNLCAERHYDTAKFNCRVAQYPFEDHNPPQLELIKPFCEDLDQWLSEDDNHVAAIHCKAGKGRTGVMICAYLLHRGKFLKAQEALDFYGEVRTRDKKGVTIPSQRRYVYYYSYLLKNHLDYRPVALLFHKMMFETIPMFSGGTCNPQFVVCQLKVKIYSSNSGPTRREDKFMYFEFPQPLPVCGDIKVEFFHKQNKMLKKDKMFHFWVNTFFIPGPEETSEKVENGSLCDQEIDSICSIERADNDKEYLVLTLTKNDLDKANKDKANRYFSPNFKVKLYFTKTVEEPSNPEASSSTSVTPDVSDNEPDHYRYSDTTDSDPENEPFDEDQHTQITKV*
## 8                                                                                                                                                                                                                                               MAQTPAFDKPKVELHVHLDGSIKPETILYYGRRRGIALPANTAEGLLNVIGMDKPLTLPDFLAKFDYYMPAIAGCREAIKRIAYEFVEMKAKEGVVYVEVRYSPHLLANSKVEPIPWNQAEGDLTPDEVVALVGQGLQEGERDFGVKARSILCCMRHQPNWSPKVVELCKKYQQQTVVAIDLAGDETIPGSSLLPGHVQAYQAVDILKTERLGHGYHTLEDQALYNRLRQENMHFEICPWSSYLTGAWKPDTEHAVIRLKNDQANYSLNTDDPLIFKSTLDTDYQMTKRDMGFTEEEFKRLNINAAKSSFLPEDEKRELLDLLYKAYGMPPSASAGQNL*
## 9                                                                                                                                                                               MTAIIKEIVSRNKRRYQEDGFDLDLTYIYPNIIAMGFPAERLEGVYRNNIDDVVRFLDSKHKNHYKIYNLCAERHYDTAKFNCRVAQYPFEDHNPPQLELIKPFCEDLDQWLSEDDNHVAAIHCKAGKGRTGVMICAYLLHRGKFLKAQEALDFYGEVRTRDKKGVTIPSQRRYVYYYSYLLKNHLDYRPVALLFHKMMFETIPMFSGGTCNPQFVVCQLKVKIYSSNSGPTRREDKFMYFEFPQPLPVCGDIKVEFFHKQNKMLKKDKMFHFWVNTFFIPGPEETSEKVENGSLCDQEIDSICSIERADNDKEYLVLTLTKNDLDKANKDKANRYFSPNFKVKLYFTKTVEEPSNPEASSSTSVTPDVSDNEPDHYRYSDTTDSDPENEPFDEDQHTQITKV*
## 10                                                                                                                                                                                                                                                                                                                                                                                                                                     MGFPAERLEGVYRNNIDDVVRFLDSKHKNHYKIYNLCAERHYDTAKFNCRVAQYPFEDHNPPQLELIKPFCEDLDQWLSEDDNHVAAIHCKAGKGRTGVMICAYLLHRGKFLKAQEALDFYGEVRTRDKKADPTGGIPDKGIIVIGDGSSMDVIAP*
## 11         RLGDSALAPRATAAAPGRGSESPVTISRAGNAGELVSPLLLPPTIQGPGPVLNLPSAAAAPPVARAPEAAGGGSRSEDYSSSPHSAAAAARPLAAEEKQAQSLQPSSSRRSSHYPAAVQSQAAAERGASATAKSRAISILQKKPRHQQLLPSLSSFFFSHRLPDMTAIIKEIVSRNKRRYQEDGFDLDLTYIYPNIIAMGFPAERLEGVYRNNIDDVVRFLDDSKHKNHYKIYNLCAERHYDTAKFNCRVAQYPFEDHNPPQLELIKPFCEDLDQWLSEDDNHVAAIHCKAGKGRTGVMICAYLLHRGKFLKAQEALDFYGEVRTRDKKGVTIPSQRRYVYYYSYLLKNHLDYRPVALLFHKMMFETIPMFSGGTCNPQFVVCQLKVKIYSSNSGPTRREDKFMYFEFPQPLPVCGDIKVEFFHKQNKMLKKDKMFHFWVNTFFIPGPEETSEKVENGSLCDQEIDSICSIERADNDKEYLVLTLTKNDLDKANKDKANRYFSPNFKVKLYFTKTVEEPSNPEASSSTSVTPDVSDNEPDHYRYSDTTDSDPENEPFDEDQHTQITKV*
##    entrezgene
## 1         100
## 2         100
## 3         100
## 4        5728
## 5         100
## 6        5728
## 7        5728
## 8         100
## 9        5728
## 10       5728
## 11       5728

4.10 Retrieve known SNPs located on the human chromosome 8 between positions 148350 and 148612

For this example we’ll first have to connect to a different BioMart database, namely snp.

snpmart = useMart(biomart = "ENSEMBL_MART_SNP", dataset="hsapiens_snp")

The listAttributes() and listFilters() functions give us an overview of the available attributes and filters.
From these we need: refsnp_id, allele, chrom_start and chrom_strand as attributes; and as filters we’ll use: chrom_start, chrom_end and chr_name.
Note that when a chromosome name, a start position and an end position are jointly used as filters, the BioMart webservice interprets this as return everything from the given chromosome between the given start and end positions. Putting our selected attributes and filters into getBM gives:

getBM(attributes = c('refsnp_id','allele','chrom_start','chrom_strand'), 
      filters = c('chr_name','start','end'), 
      values = list(8,148350,148612), 
      mart = snpmart)
##     refsnp_id allele chrom_start chrom_strand
## 1 rs868546642    A/G      148372            1
## 2 rs547420070    A/C      148373            1
## 3  rs77274555    G/A      148391            1
## 4 rs567299969    T/A      148394            1
## 5 rs368076569    G/A      148407            1
## 6 rs745318437    C/G      148497            1
## 7 rs190721891    C/G      148576            1

4.11 Given the human gene TP53, retrieve the human chromosomal location of this gene and also retrieve the chromosomal location and RefSeq id of its homolog in mouse.

The getLDS() (Get Linked Dataset) function provides functionality to link 2 BioMart datasets which each other and construct a query over the two datasets. In Ensembl, linking two datasets translates to retrieving homology data across species. The usage of getLDS is very similar to getBM(). The linked dataset is provided by a separate Mart object and one has to specify filters and attributes for the linked dataset. Filters can either be applied to both datasets or to one of the datasets. Use the listFilters and listAttributes functions on both Mart objects to find the filters and attributes for each dataset (species in Ensembl). The attributes and filters of the linked dataset can be specified with the attributesL and filtersL arguments. Entering all this information into getLDS() gives:

human = useMart("ensembl", dataset = "hsapiens_gene_ensembl")
mouse = useMart("ensembl", dataset = "mmusculus_gene_ensembl")
getLDS(attributes = c("hgnc_symbol","chromosome_name", "start_position"),
       filters = "hgnc_symbol", values = "TP53",mart = human,
      attributesL = c("refseq_mrna","chromosome_name","start_position"), martL = mouse)
##   HGNC.symbol Chromosome.Name Gene.Start..bp. RefSeq.mRNA..e.g..NM_001195597. Chromosome.Name.1 Gene.Start..bp..1
## 1        TP53              17         7661779                                                11          69580359
## 2        TP53              17         7661779                    NM_001127233                11          69580359
## 3        TP53              17         7661779                       NM_011640                11          69580359

5 Using archived versions of Ensembl

It is possible to query archived versions of Ensembl through biomaRt. There are currently two ways to access archived versions.

5.1 Using archive = TRUE

First we list the available Ensembl archives by using the listMarts() function and setting the archive attribute to TRUE. Note that not all archives are available this way and it seems that recently this only gives access to few archives if you don’t see the version of the archive you need please look at the 2nd way to access archives.

listMarts(archive = TRUE)
##                        biomart                     version
## 1              ensembl_mart_51                  Ensembl 51
## 2                  snp_mart_51                      SNP 51
## 3                 vega_mart_51                     Vega 32
## 4              ensembl_mart_50                  Ensembl 50
## 5                  snp_mart_50                      SNP 50
## 6                 vega_mart_50                     Vega 32
## 7              ensembl_mart_49   ENSEMBL GENES 49 (SANGER)
## 8     genomic_features_mart_49            Genomic Features
## 9                  snp_mart_49                         SNP
## 10                vega_mart_49                        Vega
## 11             ensembl_mart_48   ENSEMBL GENES 48 (SANGER)
## 12    genomic_features_mart_48            Genomic Features
## 13                 snp_mart_48                         SNP
## 14                vega_mart_48                        Vega
## 15             ensembl_mart_47   ENSEMBL GENES 47 (SANGER)
## 16    genomic_features_mart_47            Genomic Features
## 17                 snp_mart_47                         SNP
## 18                vega_mart_47                        Vega
## 19    compara_mart_homology_47            Compara homology
## 20 compara_mart_multiple_ga_47 Compara multiple alignments
## 21 compara_mart_pairwise_ga_47 Compara pairwise alignments
## 22             ensembl_mart_46   ENSEMBL GENES 46 (SANGER)
## 23    genomic_features_mart_46            Genomic Features
## 24                 snp_mart_46                         SNP
## 25                vega_mart_46                        Vega
## 26    compara_mart_homology_46            Compara homology
## 27 compara_mart_multiple_ga_46 Compara multiple alignments
## 28 compara_mart_pairwise_ga_46 Compara pairwise alignments
## 29             ensembl_mart_45   ENSEMBL GENES 45 (SANGER)
## 30                 snp_mart_45                         SNP
## 31                vega_mart_45                        Vega
## 32    compara_mart_homology_45            Compara homology
## 33 compara_mart_multiple_ga_45 Compara multiple alignments
## 34 compara_mart_pairwise_ga_45 Compara pairwise alignments
## 35             ensembl_mart_44   ENSEMBL GENES 44 (SANGER)
## 36                 snp_mart_44                         SNP
## 37                vega_mart_44                        Vega
## 38    compara_mart_homology_44            Compara homology
## 39 compara_mart_pairwise_ga_44 Compara pairwise alignments
## 40             ensembl_mart_43   ENSEMBL GENES 43 (SANGER)
## 41                 snp_mart_43                         SNP
## 42                vega_mart_43                        Vega
## 43    compara_mart_homology_43            Compara homology
## 44 compara_mart_pairwise_ga_43 Compara pairwise alignments

Next we select the archive we want to use using the useMart() function, again setting the archive attribute to TRUE and giving the full name of the BioMart e.g. ensembl_mart_46.

ensembl = useMart("ensembl_mart_46", dataset="hsapiens_gene_ensembl", archive = TRUE)
## Note: requested host was redirected from www.ensembl.org to http://aug2007.archive.ensembl.org:80/biomart/martservice
## When using archived Ensembl versions this sometimes can result in connecting to a newer version than the intended Ensembl version
## Check your ensembl version using listMarts(mart)
## Error in useDataset(mart = mart, dataset = dataset, verbose = verbose): The given dataset:  hsapiens_gene_ensembl , is not valid.  Correct dataset names can be obtained with the listDatasets function.

If you don’t know the dataset you want to use could first connect to the BioMart using useMart() and then use the listDatasets() function on this object. After you selected the BioMart database and dataset, queries can be performed in the same way as when using the current BioMart versions.

5.2 Accessing archives through specifying the archive host

Use the http://www.ensembl.org website and go down the bottom of the page. Click on ‘view in Archive’ and select the archive you need. Copy the url and use that url as shown below to connect to the specified BioMart database. The example below shows how to query Ensembl 54.

listMarts(host='may2009.archive.ensembl.org')
##                biomart              version
## 1 ENSEMBL_MART_ENSEMBL           Ensembl 54
## 2     ENSEMBL_MART_SNP Ensembl Variation 54
## 3    ENSEMBL_MART_VEGA              Vega 35
## 4             REACTOME   Reactome(CSHL US) 
## 5     wormbase_current   WormBase (CSHL US)
## 6                pride       PRIDE (EBI UK)
ensembl54=useMart(host='may2009.archive.ensembl.org', biomart='ENSEMBL_MART_ENSEMBL')
ensembl54=useMart(host='may2009.archive.ensembl.org', biomart='ENSEMBL_MART_ENSEMBL', dataset='hsapiens_gene_ensembl')

6 Using a BioMart other than Ensembl

To demonstrate the use of the biomaRt package with non-Ensembl databases the next query is performed using the Wormbase ParaSite BioMart. In this example, we use the listMarts() function to find the name of the available marts, given the URL of Wormbase. We use this to connect to Wormbase BioMart, find and select the gene dataset, and print the first 6 available attributes and filters. Then we use a list of gene names as filter and retrieve associated transcript IDs and the transcript biotype.

listMarts(host = "parasite.wormbase.org")
##         biomart       version
## 1 parasite_mart ParaSite Mart
wormbase = useMart(biomart = "parasite_mart", host = "parasite.wormbase.org")
listDatasets(wormbase)
##     dataset         description version
## 1 wbps_gene All Species (WBPS7)       2
wormbase <- useDataset(mart = wormbase, dataset = "wbps_gene")
head(listFilters(wormbase))
##                  name     description
## 1     species_id_1010          Genome
## 2 nematode_clade_1010  Nematode Clade
## 3     chromosome_name Chromosome name
## 4               start           Start
## 5                 end             End
## 6              strand          Strand
head(listAttributes(wormbase))
##                      name        description         page
## 1          species_id_key      Internal Name feature_page
## 2    production_name_1010     Genome project feature_page
## 3       display_name_1010        Genome name feature_page
## 4        taxonomy_id_1010        Taxonomy ID feature_page
## 5 assembly_accession_1010 Assembly accession feature_page
## 6     nematode_clade_1010     Nematode clade feature_page
getBM(attributes = c("external_gene_id","ensembl_transcript_id","transcript_biotype"), 
      filters="gene_name", 
      values=c("unc-26","his-33"), 
      mart=wormbase)
##   external_gene_id ensembl_transcript_id transcript_biotype
## 1           his-33              F17E9.13     protein_coding
## 2           unc-26               JC8.10a     protein_coding
## 3           unc-26               JC8.10b     protein_coding
## 4           unc-26             JC8.10c.1     protein_coding
## 5           unc-26             JC8.10c.2     protein_coding
## 6           unc-26               JC8.10d     protein_coding

7 biomaRt helper functions

This section describes a set of biomaRt helper functions that can be used to export FASTA format sequences, retrieve values for certain filters and exploring the available filters and attributes in a more systematic manner.

7.1 exportFASTA

The data.frames obtained by the getSequence function can be exported to FASTA files using the exportFASTA() function. One has to specify the data.frame to export and the filename using the file argument.

7.2 Finding out more information on filters

7.2.1 filterType

Boolean filters need a value TRUE or FALSE in biomaRt. Setting the value TRUE will include all information that fulfill the filter requirement. Setting FALSE will exclude the information that fulfills the filter requirement and will return all values that don’t fulfill the filter. For most of the filters, their name indicates if the type is a boolean or not and they will usually start with “with”. However this is not a rule and to make sure you got the type right you can use the function filterType() to investigate the type of the filter you want to use.

filterType("with_affy_hg_u133_plus_2",ensembl)
## [1] "boolean_list"

7.2.2 filterOptions

Some filters have a limited set of values that can be given to them. To know which values these are one can use the filterOptions() function to retrieve the predetermed values of the respective filter.

filterOptions("biotype",ensembl)
## [1] "[3prime_overlapping_ncRNA,antisense,bidirectional_promoter_lncRNA,IG_C_gene,IG_C_pseudogene,IG_D_gene,IG_J_gene,IG_J_pseudogene,IG_pseudogene,IG_V_gene,IG_V_pseudogene,lincRNA,macro_lncRNA,miRNA,misc_RNA,Mt_rRNA,Mt_tRNA,non_coding,polymorphic_pseudogene,processed_pseudogene,processed_transcript,protein_coding,pseudogene,ribozyme,rRNA,scaRNA,scRNA,sense_intronic,sense_overlapping,snoRNA,snRNA,sRNA,TEC,transcribed_processed_pseudogene,transcribed_unitary_pseudogene,transcribed_unprocessed_pseudogene,TR_C_gene,TR_D_gene,TR_J_gene,TR_J_pseudogene,TR_V_gene,TR_V_pseudogene,unitary_pseudogene,unprocessed_pseudogene,vaultRNA]"

If there are no predetermed values e.g. for the entrezgene filter, then filterOptions() will return the type of filter it is. And most of the times the filter name or it’s description will suggest what values one case use for the respective filter (e.g. entrezgene filter will work with enterzgene identifiers as values)

7.3 Attribute Pages

For large BioMart databases such as Ensembl, the number of attributes displayed by the listAttributes() function can be very large. In BioMart databases, attributes are put together in pages, such as sequences, features, homologs for Ensembl. An overview of the attributes pages present in the respective BioMart dataset can be obtained with the attributePages() function.

pages = attributePages(ensembl)
pages
## [1] "feature_page" "structure"    "homologs"     "snp"          "snp_somatic"  "sequences"

To show us a smaller list of attributes which belong to a specific page, we can now specify this in the listAttributes() function. The set of attributes is still quite long, so we use head() to show only the first few items here.

head(listAttributes(ensembl, page="feature_page"))
##                    name           description         page
## 1       ensembl_gene_id       Ensembl Gene ID feature_page
## 2 ensembl_transcript_id Ensembl Transcript ID feature_page
## 3    ensembl_peptide_id    Ensembl Protein ID feature_page
## 4       ensembl_exon_id       Ensembl Exon ID feature_page
## 5           description           Description feature_page
## 6       chromosome_name       Chromosome Name feature_page

We now get a short list of attributes related to the region where the genes are located.

8 Local BioMart databases

The biomaRt package can be used with a local install of a public BioMart database or a locally developed BioMart database and web service. In order for biomaRt to recognize the database as a BioMart, make sure that the local database you create has a name conform with database_mart_version where database is the name of the database and version is a version number. No more underscores than the ones showed should be present in this name. A possible name is for example ensemblLocal_mart_46. ## Minimum requirements for local database installation More information on installing a local copy of a BioMart database or develop your own BioMart database and webservice can be found on http://www.biomart.org Once the local database is installed you can use biomaRt on this database by:

listMarts(host="www.myLocalHost.org", path="/myPathToWebservice/martservice")
mart=useMart("nameOfMyMart",dataset="nameOfMyDataset",host="www.myLocalHost.org", path="/myPathToWebservice/martservice")

For more information on how to install a public BioMart database see: http://www.biomart.org/install.html and follow link databases.

9 Using select()

In order to provide a more consistent interface to all annotations in Bioconductor the select(), columns(), keytypes() and keys() have been implemented to wrap some of the existing functionality above. These methods can be called in the same manner that they are used in other parts of the project except that instead of taking a AnnotationDb derived class they take instead a Mart derived class as their 1st argument. Otherwise usage should be essentially the same. You still use columns() to discover things that can be extracted from a Mart, and keytypes() to discover which things can be used as keys with select().

mart <- useMart(dataset="hsapiens_gene_ensembl",biomart='ensembl')
head(keytypes(mart), n=3)
## [1] "affy_hc_g110"        "affy_hg_focus"       "affy_hg_u133_plus_2"
head(columns(mart), n=3)
## [1] "3_utr_end"   "3_utr_end"   "3_utr_start"

And you still can use keys() to extract potential keys, for a particular key type.

k = keys(mart, keytype="chromosome_name")
head(k, n=3)
## [1] "1" "2" "3"

When using keys(), you can even take advantage of the extra arguments that are available for others keys methods.

k = keys(mart, keytype="chromosome_name", pattern="LRG")
head(k, n=3)
## character(0)

Unfortunately the keys() method will not work with all key types because they are not all supported.

But you can still use select() here to extract columns of data that match a particular set of keys (this is basically a wrapper for getBM()).

affy=c("202763_at","209310_s_at","207500_at")
select(mart, keys=affy, columns=c('affy_hg_u133_plus_2','entrezgene'),
  keytype='affy_hg_u133_plus_2')
##   affy_hg_u133_plus_2 entrezgene
## 1           207500_at        838
## 2           202763_at        836
## 3         209310_s_at        837

So why would we want to do this when we already have functions like getBM()? For two reasons: 1) for people who are familiar with select and it’s helper methods, they can now proceed to use biomaRt making the same kinds of calls that are already familiar to them and 2) because the select method is implemented in many places elsewhere, the fact that these methods are shared allows for more convenient programmatic access of all these resources. An example of a package that takes advantage of this is the OrganismDbi package. Where several packages can be accessed as if they were one resource.

10 Session Info

sessionInfo()
## R version 3.3.1 (2016-06-21)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 16.04.1 LTS
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C               LC_TIME=en_US.UTF-8        LC_COLLATE=C              
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8    LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C             LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] biomaRt_2.30.0  BiocStyle_2.2.0
## 
## loaded via a namespace (and not attached):
##  [1] Rcpp_0.12.7          IRanges_2.8.0        XML_3.98-1.4         digest_0.6.10        assertthat_0.1      
##  [6] bitops_1.0-6         DBI_0.5-1            stats4_3.3.1         formatR_1.4          magrittr_1.5        
## [11] RSQLite_1.0.0        evaluate_0.10        stringi_1.1.2        S4Vectors_0.12.0     rmarkdown_1.1       
## [16] tools_3.3.1          stringr_1.1.0        Biobase_2.34.0       RCurl_1.95-4.8       parallel_3.3.1      
## [21] yaml_2.1.13          BiocGenerics_0.20.0  AnnotationDbi_1.36.0 htmltools_0.3.5      knitr_1.14          
## [26] tibble_1.2
warnings()
## NULL
biomaRt/inst/scripts/0000755000175400017540000000000013001231112015621 5ustar00biocbuildbiocbuildbiomaRt/inst/scripts/Integration-NP.R0000644000175400017540000001373213001231112020550 0ustar00biocbuildbiocbuild###-------------------------------------------------- ### Step 1 ###-------------------------------------------------- library('biomaRt') library('affy') library('gplots') library('lattice') ###-------------------------------------------------- ### Step 2 ###-------------------------------------------------- sampleAnnot = read.AnnotatedDataFrame('E-TABM-157.txt',row.names = 'Array.Data.File') mRNAraw = ReadAffy(phenoData = sampleAnnot, sampleNames = sampleAnnot$Source.Name) ###-------------------------------------------------- ### Step 3 ###-------------------------------------------------- mRNA = rma(mRNAraw) ###-------------------------------------------------- ### Step 4 ###-------------------------------------------------- probesetvar = apply(exprs(mRNA), 1, var) ord = order(probesetvar, decreasing=TRUE)[1:200] pca = prcomp(t(exprs(mRNA)[ord,]), scale=TRUE) typeColors = c('Lu'='firebrick1','BaA'='dodgerblue2','BaB'='darkblue') plot(pca$x[, 1:2], pch=16, col=typeColors[as.character(mRNA$CancerType)], xlab='PC1', ylab='PC2', asp=1) legend('topleft', c('luminal', 'basal A', 'basal B'), fill=typeColors) ###-------------------------------------------------- ### Step 5 ###-------------------------------------------------- cghData = read.csv('aCGH.csv', header=TRUE, row.names=1) cgh = new('ExpressionSet', exprs = as.matrix(cghData[,4:56])) featureData(cgh) = as(cghData[,1:3], 'AnnotatedDataFrame') ###-------------------------------------------------- ### Step 6 ###-------------------------------------------------- chr1 = which(featureData(cgh)$Chrom == 1) clColors = c('MCF10A' = 'dodgerblue3', 'BT483' = 'orange', 'BT549' = 'olivedrab') logRatio = exprs(cgh)[chr1, names(clColors)] kb = rep(featureData(cgh)$kb[chr1], times=ncol(logRatio)) clName = rep(names(clColors), each=nrow(logRatio)) print(xyplot( logRatio ~ kb | clName, pch=16, layout=c(1,3), ylim=c(-0.5, 1.1), panel=function(...){ panel.xyplot(...,col=clColors[panel.number()]) panel.abline(h=0, col='firebrick2') })) ###-------------------------------------------------- ### Step 7 ###-------------------------------------------------- ensembl = useMart('ensembl', dataset='hsapiens_gene_ensembl') probes = getBM(attributes = c('affy_hg_u133a', 'start_position'), filters = c('chromosome_name', 'with_affy_hg_u133a'), values = list(1, TRUE), mart = ensembl) ###-------------------------------------------------- ### Step 8 ###-------------------------------------------------- xpr = exprs(mRNA)[probes[,'affy_hg_u133a'], c('BT549','BT483')] pos = probes[,'start_position'] plot(xpr, pch=16, cex=0.5, col=ifelse(pos>140e6, 'red', 'darkgrey')) ###-------------------------------------------------- ### Step 9 ###-------------------------------------------------- logRatios = xpr[,2] - xpr[,1] t.test(logRatios ~ (pos>140e6)) ###-------------------------------------------------- ### Step 10 ###-------------------------------------------------- proteinData = read.csv('mmc6.csv', header=TRUE, row.names=1) protein = new('ExpressionSet', exprs = as.matrix(proteinData)) ###-------------------------------------------------- ### Step 11 ###-------------------------------------------------- prmax = apply(exprs(protein), 1, max) barplot(prmax, las=2) ###-------------------------------------------------- ### Step 12 ###-------------------------------------------------- hmColors = colorRampPalette(c('white', 'darkblue'))(256) sideColors = typeColors[as.character(pData(mRNA)[ sampleNames(protein), 'CancerType'])] sideColors[is.na(sideColors)] = 'grey' heatmap.2(exprs(protein)/prmax, col=hmColors, trace='none', ColSideColors = sideColors) ###-------------------------------------------------- ### Step 13 ###-------------------------------------------------- samples = intersect(sampleNames(protein), sampleNames(mRNA)) samples = intersect(samples, sampleNames(cgh)) mRNA = mRNA[,samples] protein = protein[,samples] cgh = cgh[,samples] ###-------------------------------------------------- ### Step 14 ###-------------------------------------------------- map = getBM(attributes = c('ensembl_gene_id', 'affy_hg_u133a', 'hgnc_symbol'), filters = c('hgnc_symbol', 'with_hgnc', 'with_affy_hg_u133a'), values = list(featureNames(protein), TRUE, TRUE), mart = ensembl) head(map) ###-------------------------------------------------- ### Step 15 ###-------------------------------------------------- geneProbesetsAll = split(map$affy_hg_u133a, map$hgnc_symbol) table(listLen(geneProbesetsAll)) ###-------------------------------------------------- ### Step 16 ###-------------------------------------------------- geneProbesets = lapply(geneProbesetsAll, function(x) { good = grep('[0-9]._at', x) if (length(good)>0) x[good] else x }) summaries = lapply(geneProbesets, function(i) { colMeans(exprs(mRNA)[i,,drop=FALSE]) }) summarized_mRNA = do.call(rbind, summaries) ###-------------------------------------------------- ### Step 17 ###-------------------------------------------------- colors = c('orange','olivedrab') correlation = cor(summarized_mRNA['AURKA',], exprs(protein)['AURKA',], method='spearman') matplot(cbind( summarized_mRNA['AURKA', ], log2(exprs(protein)['AURKA', ])), type='l', col=colors, lwd=2, lty=1, ylab='mRNA and protein expression levels', xlab='cell lines', main=bquote(rho==.(round(correlation, 3)))) legend('bottomright', c('mRNA','protein'), fill=colors) ###-------------------------------------------------- ### Step 18 ###-------------------------------------------------- samples = sampleNames(protein)[c(5,11,16,24)] v_mRNA = as.vector(summarized_mRNA[,samples]) v_protein = as.vector(exprs(protein)[ rownames(summarized_mRNA), samples]) print(xyplot( v_protein ~ v_mRNA | rep(samples, each = nrow(summarized_mRNA)), pch=16, xlab = 'mRNA level', scales=list(y=list(log=TRUE)), ylab='protein level')) biomaRt/man/0000755000175400017540000000000013001231112013730 5ustar00biocbuildbiocbuildbiomaRt/man/Mart-class.Rd0000644000175400017540000000043513001231112016227 0ustar00biocbuildbiocbuild\name{Mart-class} \alias{Mart-class} \alias{show,Mart-method} \title{Class Mart} \description{Represents a Mart class, containing connections to different BioMarts} \section{Methods}{ \describe{\code{show} Print summary of the object} } \author{Steffen Durinck} \keyword{methods} biomaRt/man/NP2009code.Rd0000644000175400017540000000104313001231112015700 0ustar00biocbuildbiocbuild\name{NP2009code} \alias{NP2009code} \title{Display the analysis code from the 2009 Nature protocols paper} \description{This function opens an editor displaying the analysis code of the Nature Protocols 2009 paper} \usage{NP2009code()} \details{The \code{\link{edit}} function uses \code{getOption("editor")} to select the editor. Use, for instance, \code{options(editor="emacs")} to set another editor.} \author{Steffen Durinck, Wolfgang Huber} \seealso{\code{\link{edit}}} \examples{ if(interactive()){ NP2009code() } } \keyword{methods} biomaRt/man/attributePages.Rd0000644000175400017540000000125013001231112017200 0ustar00biocbuildbiocbuild\name{attributePages} \alias{attributePages} \title{Gives a summary of the attribute pages} \description{Attributes in BioMart databases are grouped together in attribute pages. The attributePages function gives a summary of the attribute categories and groups present in the BioMart. These page names can be used to display only a subset of the available attributes in the listAttributes function.} \usage{attributePages(mart)} \arguments{ \item{mart}{object of class Mart, created with the useMart function.} } \author{Steffen Durinck} \examples{ if(interactive()){ mart = useMart("ensembl", dataset="hsapiens_gene_ensembl") attributeSummary(mart) } } \keyword{methods} biomaRt/man/exportFASTA.Rd0000644000175400017540000000117213001231112016320 0ustar00biocbuildbiocbuild\name{exportFASTA} \alias{exportFASTA} \title{Exports getSequence results to FASTA format} \description{Exports getSequence results to FASTA format} \usage{exportFASTA(sequences, file)} \arguments{ \item{sequences}{A data.frame that was the output of the getSequence function} \item{file}{File to which you want to write the data} } \author{Steffen Durinck} \examples{ if(interactive()){ mart <- useMart("ensembl", dataset="hsapiens_gene_ensembl") #seq<-getSequence(chromosome=c(2,2),start=c(100000,30000),end=c(100300,30500),mart=mart) #exportFASTA(seq,file="test.fasta") martDisconnect(mart = mart) } } \keyword{methods} biomaRt/man/filterOptions.Rd0000644000175400017540000000077213001231112017066 0ustar00biocbuildbiocbuild\name{filterOptions} \alias{filterOptions} \title{Displays the filter options} \description{Displays a set of predetermed values for the specified filter (if available).} \usage{filterOptions(filter,mart)} \arguments{ \item{filter}{A valid filter name.} \item{mart}{object of class Mar created using the useMart functiont} } \author{Steffen Durinck} \examples{ if(interactive()){ mart = useMart("ensembl", dataset="hsapiens_gene_ensembl") filterOptions("chromosome_name", mart) } } \keyword{methods} biomaRt/man/filterType.Rd0000644000175400017540000000100613001231112016343 0ustar00biocbuildbiocbuild\name{filterType} \alias{filterType} \title{Displays the filter type} \description{Displays the type of the filer given a filter name.} \usage{filterType(filter,mart)} \arguments{ \item{filter}{A valid filter name. Valid filters are given by the listFilters function} \item{mart}{object of class Mart, created using the useMart function} } \author{Steffen Durinck} \examples{ if(interactive()){ mart = useMart("ensembl", dataset="hsapiens_gene_ensembl") filterType("chromosome_name", mart) } } \keyword{methods} biomaRt/man/getBM.Rd0000644000175400017540000000604313001231112015220 0ustar00biocbuildbiocbuild\name{getBM} \alias{getBM} \title{Retrieves information from the BioMart database} \description{This function is the main biomaRt query function. Given a set of filters and corresponding values, it retrieves the user specified attributes from the BioMart database one is connected to.} \usage{getBM(attributes, filters = "", values = "", mart, curl = NULL, checkFilters = TRUE, verbose = FALSE, uniqueRows = TRUE, bmHeader = FALSE, quote = "\"")} \value{A \code{data.frame}. There is no implicit mapping between its rows and the function arguments (e.g. \code{filters}, \code{values}), therefore make sure to have the relevant identifier(s) returned by specifying them in \code{attributes}. See Examples.} \arguments{ \item{attributes}{Attributes you want to retrieve. A possible list of attributes can be retrieved using the function listAttributes.} \item{filters}{Filters (one or more) that should be used in the query. A possible list of filters can be retrieved using the function listFilters.} \item{values}{Values of the filter, e.g. vector of affy IDs. If multiple filters are specified then the argument should be a list of vectors of which the position of each vector corresponds to the position of the filters in the filters argument.} \item{mart}{object of class Mart, created with the useMart function.} \item{curl}{An optional 'CURLHandle' object, that can be used to speed up getBM when used in a loop.} \item{checkFilters}{Sometimes attributes where a value needs to be specified, for example upstream\_flank with value 20 for obtaining upstream sequence flank regions of length 20bp, are treated as filters in BioMarts. To enable such a query to work, one must specify the attribute as a filter and set checkFilters = FALSE for the query to work.} \item{verbose}{When using biomaRt in webservice mode and setting verbose to TRUE, the XML query to the webservice will be printed.} \item{uniqueRows}{If the result of a query contains multiple identical rows, setting this argument to TRUE (default) will result in deleting the duplicated rows in the query result at the server side.} \item{bmHeader}{Boolean to indicate if the result retrieved from the BioMart server should include the data headers or not, defaults to FALSE. This should only be switched on if the default behavior results in errors, setting to on might still be able to retrieve your data in that case} \item{quote}{Sometimes parsing of the results fails due to errors in the Ensembl data fields such as containing a quote, in such cases you can try to change the value of quote to try to still parse the results.} } \author{Steffen Durinck} \examples{ if (interactive()) { mart <- useMart("ensembl") datasets <- listDatasets(mart) mart <- useDataset("hsapiens_gene_ensembl",mart) getBM(attributes = c("affy_hg_u95av2", "hgnc_symbol", "chromosome_name", "band"), filters = "affy_hg_u95av2", values = c("1939_at","1503_at","1454_at"), mart = mart) # rows are sorted by `affy_hg_u95av2`, and in different order than the `values` argument } } \keyword{methods} biomaRt/man/getBMlist.Rd0000644000175400017540000000300413001231112016106 0ustar00biocbuildbiocbuild\name{getBMlist} \alias{getBMlist} \title{Retrieves information from the BioMart database} \description{This function is the main biomaRt query function. Given a set of filters and corresponding values, it retrieves the user specified attributes from the BioMart database one is connected to} \usage{getBMlist(attributes, filters = "", values = "", mart, list.names = NULL, na.value = NA, verbose = FALSE, giveWarning = TRUE)} \arguments{ \item{attributes}{Attributes you want to retrieve. A possible list of attributes can be retrieved using the function listAttributes.} \item{filters}{Filters (one or more) that should be used in the query. A possible list of filters can be retrieved using the function listFilters.} \item{values}{Values of the filter, e.g. vector of affy IDs. If multiple filters are specified then the argument should be a list of vectors of which the position of each vector corresponds to the position of the filters in the filters argument.} \item{mart}{object of class Mart, created with the useMart function.} \item{list.names}{names for objects in list} \item{na.value}{value to give when result is empty} \item{verbose}{When using biomaRt in webservice mode and setting verbose to TRUE, the XML query to the webservice will be printed.} \item{giveWarning}{Gives a warning about best practices of biomaRt and recommends using getBM instead of getBMlist} } \author{Steffen Durinck} \examples{ if(interactive()){ mart <- useMart("ensembl") datasets <- listDatasets(mart) } } \keyword{methods} biomaRt/man/getGene.Rd0000644000175400017540000000235513001231112015602 0ustar00biocbuildbiocbuild\name{getGene} \alias{getGene} \title{Retrieves gene annotation information given a vector of identifiers} \description{This function retrieves gene annotations from Ensembl given a vector of identifiers. Annotation includes chromsome name, band, start position, end position, gene description and gene symbol. A wide variety of identifiers is available in Ensembl, these can be found with the listFilters function.} \usage{getGene( id, type, mart)} \arguments{ \item{id}{vector of gene identifiers one wants to annotate} \item{type}{type of identifier, possible values can be obtained by the listFilters function. Examples are entrezgene, hgnc\_symbol (for hugo gene symbol), ensembl\_gene\_id, unigene, agilentprobe, affy\_hg\_u133\_plus\_2, refseq\_dna, etc.} \item{mart}{object of class Mart, containing connections to the BioMart databases. You can create such an object using the function useMart.} } \author{Steffen Durinck} \examples{ if(interactive()){ mart = useMart("ensembl", dataset="hsapiens_gene_ensembl") #example using affy id g = getGene( id = "1939_at", type = "affy_hg_u95av2", mart = mart) show(g) #example using Entrez Gene id g = getGene( id = "100", type = "entrezgene", mart = mart) show(g) } } \keyword{methods} biomaRt/man/getLDS.Rd0000644000175400017540000000430413001231112015342 0ustar00biocbuildbiocbuild\name{getLDS} \alias{getLDS} \title{Retrieves information from two linked datasets} \description{This function is the main biomaRt query function that links 2 datasets and retrieves information from these linked BioMart datasets. In Ensembl this translates to homology mapping.} \usage{getLDS(attributes, filters = "", values = "", mart, attributesL, filtersL = "", valuesL = "", martL, verbose = FALSE, uniqueRows = TRUE, bmHeader=TRUE)} \arguments{ \item{attributes}{Attributes you want to retrieve of primary dataset. A possible list of attributes can be retrieved using the function listAttributes.} \item{filters}{Filters that should be used in the query. These filters will be applied to primary dataset. A possible list of filters can be retrieved using the function listFilters.} \item{values}{Values of the filter, e.g. list of affy IDs} \item{mart}{object of class Mart created with the useMart function.} \item{attributesL}{Attributes of linked dataset that needs to be retrieved} \item{filtersL}{Filters to be applied to the linked dataset} \item{valuesL}{Values for the linked dataset filters} \item{martL}{Mart object representing linked dataset} \item{verbose}{When using biomaRt in webservice mode and setting verbose to TRUE, the XML query to the webservice will be printed. Alternatively in MySQL mode the MySQL query will be printed.} \item{uniqueRows}{Logical to indicate if the BioMart web service should return unique rows only or not. Has the value of either TRUE or FALSE} \item{bmHeader}{Boolean to indicate if the result retrieved from the BioMart server should include the data headers or not, defaults to TRUE. This should only be switched off if the default behavior results in errors, setting to off might still be able to retrieve your data in that case} } \author{Steffen Durinck} \examples{ if(interactive()){ human = useMart("ensembl", dataset = "hsapiens_gene_ensembl") mouse = useMart("ensembl", dataset = "mmusculus_gene_ensembl") getLDS(attributes = c("hgnc_symbol","chromosome_name", "start_position"), filters = "hgnc_symbol", values = "TP53", mart = human, attributesL = c("chromosome_name","start_position"), martL = mouse) } } \keyword{methods} biomaRt/man/getSequence.Rd0000644000175400017540000000631313001231112016472 0ustar00biocbuildbiocbuild\name{getSequence} \alias{getSequence} \title{Retrieves sequences} \description{This function retrieves sequences given the chomosome, start and end position or a list of identifiers. Using getSequence in web service mode (default) generates 5' to 3' sequences of the requested type on the correct strand. The type of sequence returned can be specified by the seqType argument which takes the following values: 'cdna';'peptide' for protein sequences;'3utr' for 3' UTR sequences,'5utr' for 5' UTR sequences; 'gene\_exon' for exon sequences only; 'transcript\_exon\_intron' gives the full unspliced transcript, that is exons + introns;'gene\_exon\_intron' gives the exons + introns of a gene;'coding' gives the coding sequence only;'coding\_transcript\_flank' gives the flanking region of the transcript including the UTRs, this must be accompanied with a given value for the upstream or downstream attribute;'coding\_gene\_flank' gives the flanking region of the gene including the UTRs, this must be accompanied with a given value for the upstream or downstream attribute; 'transcript\_flank' gives the flanking region of the transcript exculding the UTRs, this must be accompanied with a given value for the upstream or downstream attribute; 'gene\_flank' gives the flanking region of the gene excluding the UTRs, this must be accompanied with a given value for the upstream or downstream attribute. In MySQL mode the getSequence function is more limited and the sequence that is returned is the 5' to 3'+ strand of the genomic sequence, given a chromosome, as start and an end position. So if the sequence of interest is the minus strand, one has to compute the reverse complement of the retrieved sequence, which can be done using functions provided in the matchprobes package. The biomaRt vignette contains more examples on how to use this function.} \usage{getSequence( chromosome, start, end, id, type, seqType, upstream, downstream, mart, verbose=FALSE)} \arguments{ \item{chromosome}{Chromosome name} \item{start}{start position of sequence on chromosome} \item{end}{end position of sequence on chromosome} \item{id}{ An identifier or vector of identifiers.} \item{type}{The type of identifier used. Supported types are hugo, ensembl, embl, entrezgene, refseq, ensemblTrans and unigene. Alternatively one can also use a filter to specify the type. Possible filters are given by the listFilters function} \item{seqType}{Type of sequence that you want to retrieve. Allowed seqTypes are: cdna, peptide, 3utr, 5utr, genomic} \item{upstream}{To add the upstream sequence of a specified number of basepairs to the output.} \item{downstream}{To add the downstream sequence of a specified number of basepairs to the output.} \item{mart}{object of class Mart created using the useMart function} \item{verbose}{If verbose = TRUE then the XML query that was send to the webservice will be displayed.} } \author{Steffen Durinck} \examples{ if(interactive()){ mart <- useMart("ensembl",dataset="hsapiens_gene_ensembl") seq = getSequence(id="BRCA1", type="hgnc_symbol", seqType="peptide", mart = mart) show(seq) seq = getSequence(id="1939_at", type="affy_hg_u95av2", seqType="gene_flank",upstream = 20, mart = mart) show(seq) } } \keyword{methods} biomaRt/man/getXML.Rd0000644000175400017540000000165413001231112015365 0ustar00biocbuildbiocbuild\name{getXML} \alias{getXML} \title{Retrieves information from the BioMart database using an XML query} \description{This function is a low level query function bypassing lots of biomaRts internal controls. It allows for a direct XML query to a known BioMart webservice host.} \usage{getXML(host="http://www.biomart.org/biomart/martservice?", xmlquery)} \arguments{ \item{host}{URL to BioMart webservice, is set to http://www.biomart.org/biomart/martservice? by default} \item{xmlquery}{XML query that needs to be send to the webservice} } \author{Steffen Durinck} \examples{ if(interactive()){ getXML(xmlquery=" ") } } \keyword{methods} biomaRt/man/listAttributes.Rd0000644000175400017540000000176613001231112017253 0ustar00biocbuildbiocbuild\name{listAttributes} \alias{listAttributes} \title{lists the attributes available in the selected dataset} \description{Attributes are the outputs of a biomaRt query, they are the information we want to retrieve. For example if we want to retrieve all entrez gene identifiers of genes located on chromosome X, entrezgene will be the attribute we use in the query. The listAttributes function lists the available attributes in the selected dataset} \usage{listAttributes(mart, page,what = c("name","description","page"))} \arguments{ \item{mart}{object of class Mart created using the useMart function} \item{page}{Show only the attributes that belong to the specified attribute page.} \item{what}{vector of types of information about the attributes that need to be displayed. Can have values like name, description, fullDescription, page} } \author{Steffen Durinck} \examples{ if(interactive()){ ensembl = useMart("ensembl", dataset="hsapiens_gene_ensembl") listAttributes(ensembl) } } \keyword{methods} biomaRt/man/listDatasets.Rd0000644000175400017540000000116413001231112016665 0ustar00biocbuildbiocbuild\name{listDatasets} \alias{listDatasets} \title{lists the datasets available in the selected BioMart database} \description{Lists the datasets available in the selected BioMart database} \usage{listDatasets(mart, verbose = FALSE)} \arguments{ \item{mart}{object of class Mart created with the useMart function} \item{verbose}{Give detailed output of what the method is doing, for debugging purposes} } \author{Steffen Durinck} \examples{ if(interactive()){ #marts <- listMarts() #index<-grep("ensembl",marts) #mart <- useMart(marts[index]) #listDatasets(mart = mart) #martDisconnect(mart = mart) } } \keyword{methods} biomaRt/man/listEnsembl.Rd0000644000175400017540000000214713001231112016504 0ustar00biocbuildbiocbuild\name{listEnsembl} \alias{listEnsembl} \title{lists the available BioMart databases hosted by Ensembl} \description{This function returns a list of BioMart databases hosted by Ensembl. To establish a connection use the useMart function.} \usage{listEnsembl(mart = NULL,host = "www.ensembl.org", version = NULL, GRCh = NULL, mirror = NULL, verbose = FALSE)} \arguments{ \item{mart}{mart object created with the useEnsembl function. This is optional, as you usually use listMarts to see which marts there are to connect to.} \item{host}{Host to connect to if different then www.ensembl.org} \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}{Mirror to connect to [uswest,useast,asia], If no mirror is specified the default will be used which is www.ensembl.org hosted in the UK} \item{verbose}{Give detailed output of what the method is doing, for debugging purposes} } \author{Steffen Durinck} \examples{ if(interactive()){ listEnsembl() } } \keyword{methods} biomaRt/man/listFilters.Rd0000644000175400017540000000164713001231112016533 0ustar00biocbuildbiocbuild\name{listFilters} \alias{listFilters} \title{lists the filters available in the selected dataset} \description{Filters are what we use as inputs for a biomaRt query. For example, if we want to retrieve all entrezgene identifiers on chromosome X, \code{chromosome} will be the filter, with corresponding value X.} \usage{listFilters(mart, what = c("name", "description"))} \arguments{ \item{mart}{object of class \code{Mart} created using the \code{\link{useMart}} function} \item{what}{character vector indicating what information to display about the available filters. Valid values are \code{name}, \code{description}, \code{options}, \code{fullDescription}, \code{filters}, \code{type}, \code{operation}, \code{filters8}, \code{filters9}.} } \author{Steffen Durinck} \examples{ if(interactive()){ mart = useMart("ensembl", dataset="hsapiens_gene_ensembl") listFilters(mart) } } \keyword{methods} biomaRt/man/listMarts.Rd0000644000175400017540000000243513001231112016205 0ustar00biocbuildbiocbuild\name{listMarts} \alias{listMarts} \title{lists the avilable BioMart databases} \description{This function returns a list of BioMart databases to which biomaRt can connect to. By default all public BioMart databases are displayed. To establish a connection use the useMart function.} \usage{listMarts(mart = NULL, host="www.ensembl.org", path="/biomart/martservice", port=80, includeHosts = FALSE, archive=FALSE, ssl.verifypeer=TRUE, verbose = FALSE)} \arguments{ \item{mart}{mart object created with the useMart function. This is optional, as you usually use listMarts to see which marts there are to connect to.} \item{host}{host to connect to if different then www.biomart.org} \item{path}{path to martservice that should be pasted behind the host to get to web service URL} \item{port}{port to use in HTTP communication} \item{includeHosts}{boolean to indicate if function should return host of the BioMart databases} \item{archive}{Boolean to indicate if you want to access archived versions of BioMart database} \item{ssl.verifypeer}{Set SSL peer verification on or off. By default ssl.verifypeer is set to TRUE} \item{verbose}{Give detailed output of what the method is doing, for debugging purposes} } \author{Steffen Durinck} \examples{ if(interactive()){ listMarts() } } \keyword{methods} biomaRt/man/select.Rd0000644000175400017540000000736213001231112015506 0ustar00biocbuildbiocbuild%% actual page name \alias{select-methods} \name{select-methods} %% for methods \alias{keys,Mart-method} \alias{columns,Mart-method} \alias{keytypes,Mart-method} \alias{select,Mart-method} %% for convenience \alias{keys} \alias{columns} \alias{keytypes} \alias{select} \title{Retrieve information from the BioMart databases} \description{ \code{select}, \code{columns} and \code{keys} are used together to extract data from a \code{Mart} object. These functions work much the same as the classic biomaRt functions such as \code{getBM} etc. and are provide here to make this easier for people who are comfortable using these methods from other Annotation packages. Examples of other objects in other packages where you can use these methods include (but are not limited to): \code{ChipDb}, \code{OrgDb} \code{GODb}, \code{InparanoidDb} and \code{ReactomeDb}. \code{columns} shows which kinds of data can be returned from the \code{Mart} object. \code{keytypes} allows the user to discover which keytypes can be passed in to \code{select} or \code{keys} as the \code{keytype} argument. \code{keys} returns keys from the \code{Mart} of the type specified by it's \code{keytype} argument. \code{select} is meant to be used with these other methods and has arguments that take the kinds of values that these other methods return. \code{select} will retrieve the results as a data.frame based on parameters for selected \code{keys} and \code{columns} and \code{keytype} arguments. } \usage{ columns(x) keytypes(x) keys(x, keytype, ...) select(x, keys, columns, keytype, ...) } \arguments{ \item{x}{the \code{Mart} object. The dataset of the \code{Mart} object must already be specified for all of these methods.} \item{keys}{the keys to select records for from the database. Keys for some keytypes can be extracted by using the \code{keys} method.} \item{columns}{the columns or kinds of things that can be retrieved from the database. As with \code{keys}, all possible columns are returned by using the \code{columns} method.} \item{keytype}{the keytype that matches the keys used. For the \code{select} methods, this is used to indicate the kind of ID being used with the keys argument. For the \code{keys} method this is used to indicate which kind of keys are desired from \code{keys} } \item{...}{other arguments. These include: \describe{ \item{pattern:}{the pattern to match (used by keys)} \item{column:}{the column to search on. This is used by keys and is for when the thing you want to pattern match is different from the keytype, or when you want to simply want to get keys that have a value for the thing specified by the column argument.} \item{fuzzy:}{TRUE or FALSE value. Use fuzzy matching? (this is used with pattern by the keys method)} } } } \value{ \code{keys},\code{columns} and \code{keytypes} each return a character vector or possible values. \code{select} returns a data.frame. } \author{Marc Carlson} \examples{ ## 1st create a Mart object and specify the dataset mart<-useMart(dataset="hsapiens_gene_ensembl",biomart='ensembl') ## you can list the keytypes keytypes(mart) ## you can list the columns columns(mart) ## And you can extract keys when this is supported for your keytype of interest k = keys(mart, keytype="chromosome_name") head(k) ## You can even do some pattern matching on the keys k = keys(mart, keytype="chromosome_name", pattern="LRG") head(k) ## Finally you can use select to extract records for things that you are ## interested in. affy=c("202763_at","209310_s_at","207500_at") select(mart, keys=affy, columns=c('affy_hg_u133_plus_2','entrezgene'), keytype='affy_hg_u133_plus_2') } \keyword{methods} biomaRt/man/useDataset.Rd0000644000175400017540000000120713001231112016321 0ustar00biocbuildbiocbuild\name{useDataset} \alias{useDataset} \title{Select a dataset to use and updates Mart object} \description{This function selects a dataset and updates the Mart object} \usage{useDataset(dataset,mart, verbose = FALSE)} \arguments{ \item{dataset}{Dataset you want to use. List of possible datasets can be retrieved using the function listDatasets} \item{mart}{Mart object created with the useMart function} \item{verbose}{Give detailed output of what the method is doing, for debugging} } \author{Steffen Durinck} \examples{ if(interactive()){ mart=useMart("ensembl") mart=useDataset("hsapiens_gene_ensembl", mart = mart) } } \keyword{methods} biomaRt/man/useEnsembl.Rd0000644000175400017540000000343213001231112016323 0ustar00biocbuildbiocbuild\name{useEnsembl} \alias{useEnsembl} \title{Connects to the selected BioMart database and dataset hosted by Ensembl} \description{A first step in using the biomaRt package is to select a BioMart database and dataset to use. The useEnsembl function enables one to connect to a specified BioMart database and dataset hosted by Ensembl without having to specify the Ensembl URL. To know which BioMart databases are available see the listEnsembl function. To know which datasets are available within a BioMart database, first select the BioMart database using useMart and then use the listDatasets function on the selected BioMart, see listDatasets function.} \usage{useEnsembl(biomart, dataset,host="www.ensembl.org", version = NULL, GRCh = NULL, mirror = NULL, verbose = FALSE)} \arguments{ \item{biomart}{BioMart database name you want to connect to. Possible database names can be retrieved with the functio listEnsembl} \item{dataset}{Dataset you want to use. To see the different datasets available within a biomaRt you can e.g. do: mart = useEnsembl('ENSEMBL_MART_ENSEMBL'), followed by listDatasets(mart).} \item{host}{Host to connect to if different then www.ensembl.org} \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}{Mirror to connect to [uswest,useast,asia], If no mirror is specified the default will be used which is www.ensembl.org hosted in the UK} \item{verbose}{Give detailed output of what the method is doing while in use, for debugging} } \author{Steffen Durinck} \examples{ if(interactive()){ mart = useEnsembl("ENSEMBL_MART_ENSEMBL") mart=useMart(biomart="ensembl", dataset="hsapiens_gene_ensembl") } } \keyword{methods} biomaRt/man/useMart.Rd0000644000175400017540000000413213001231112015637 0ustar00biocbuildbiocbuild\name{useMart} \alias{useMart} \title{Connects to the selected BioMart database and dataset} \description{A first step in using the biomaRt package is to select a BioMart database and dataset to use. The useMart function enables one to connect to a specified BioMart database and dataset within this database. To know which BioMart databases are available see the listMarts function. To know which datasets are available within a BioMart database, first select the BioMart database using useMart and then use the listDatasets function on the selected BioMart, see listDatasets function.} \usage{useMart(biomart, dataset, host="www.ensembl.org", path="/biomart/martservice", port=80, archive=FALSE, ssl.verifypeer = TRUE, version, verbose = FALSE)} \arguments{ \item{biomart}{BioMart database name you want to connect to. Possible database names can be retrieved with the functio listMarts} \item{dataset}{Dataset you want to use. To see the different datasets available within a biomaRt you can e.g. do: mart = useMart('ensembl'), followed by listDatasets(mart).} \item{host}{Host to connect to if different then www.biomart.org} \item{path}{Path that should be pasted after to host to get access to the web service URL} \item{port}{port to connect to, will be pasted between host and path} \item{archive}{Boolean to indicate if you want to access archived versions of BioMart databases. Note that this gives access to only a limited number of archived BioMarts and the most recent archives are often not available. A better alternative is to leave archive = FALSE and to specify the url of the archived BioMart you want to access see vignette for an example.} \item{ssl.verifypeer}{Set SSL peer verification on or off. By default ssl.verifypeer is set to TRUE} \item{version}{Use version name instead of biomart name to specify which BioMart you want to use} \item{verbose}{Give detailed output of what the method is doing while in use, for debugging} } \author{Steffen Durinck} \examples{ if(interactive()){ mart = useMart("ensembl") mart=useMart(biomart="ensembl", dataset="hsapiens_gene_ensembl") } } \keyword{methods} biomaRt/vignettes/0000755000175400017540000000000013001246365015205 5ustar00biocbuildbiocbuildbiomaRt/vignettes/biomaRt.Rmd0000644000175400017540000006330113001231112017231 0ustar00biocbuildbiocbuild--- title: "The biomaRt users guide" author: "Steffen Durinck, Wolfgang Huber, Mike Smith" package: "`r pkg_ver('biomaRt')`" output: BiocStyle::html_document: md_extensions: "-autolink_bare_uris" vignette: > %\VignetteIndexEntry{The biomaRt users guide} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, cache = F, echo = FALSE} knitr::opts_chunk$set(error = TRUE) ``` # Introduction In recent years a wealth of biological data has become available in public data repositories. Easy access to these valuable data resources and firm integration with data analysis is needed for comprehensive bioinformatics data analysis. The `r Biocpkg("biomaRt")` package, provides an interface to a growing collection of databases implementing the [BioMart software suite](http://www.biomart.org). The package enables retrieval of large amounts of data in a uniform way without the need to know the underlying database schemas or write complex SQL queries. Examples of BioMart databases are Ensembl, Uniprot and HapMap. These major databases give `r Biocpkg("biomaRt")` users direct access to a diverse set of data and enable a wide range of powerful online queries from R. # Selecting a BioMart database and dataset Every analysis with `r Biocpkg("biomaRt")` starts with selecting a BioMart database to use. A first step is to check which BioMart web services are available. The function `listMarts()` will display all available BioMart web services ```{r annotate,echo=FALSE} ## library("annotate") options(width=120) ``` ```{r biomaRt} library("biomaRt") listMarts() ``` Note: if the function `useMart()` runs into proxy problems you should set your proxy first before calling any `r Biocpkg("biomaRt")` functions. You can do this using the Sys.putenv command: ```{r putenv, eval = FALSE} Sys.setenv("http_proxy" = "http://my.proxy.org:9999") ``` Some users have reported that the workaround above does not work, in this case an alternative proxy solution below can be tried: ```{r rCurlOptions, eval = FALSE} options(RCurlOptions = list(proxy="uscache.kcc.com:80",proxyuserpwd="------:-------")) ``` The `useMart()` function can now be used to connect to a specified BioMart database, this must be a valid name given by `listMarts()`. In the next example we choose to query the Ensembl BioMart database. ```{r ensembl1} ensembl=useMart("ensembl") ``` BioMart databases can contain several datasets, for Ensembl every species is a different dataset. In a next step we look at which datasets are available in the selected BioMart by using the function `listDatasets()`. ```{r listDatasets} listDatasets(ensembl) ``` To select a dataset we can update the `Mart` object using the function `useDataset()`. In the example below we choose to use the hsapiens dataset. ```{r ensembl2, eval=TRUE} ensembl = useDataset("hsapiens_gene_ensembl",mart=ensembl) ``` Or alternatively if the dataset one wants to use is known in advance, we can select a BioMart database and dataset in one step by: ```{r ensembl3} ensembl = useMart("ensembl",dataset="hsapiens_gene_ensembl") ``` # How to build a biomaRt query The `getBM()` function has three arguments that need to be introduced: filters, attributes and values. *Filters* define a restriction on the query. For example you want to restrict the output to all genes located on the human X chromosome then the filter *chromosome_name* can be used with value 'X'. The `listFilters()` function shows you all available filters in the selected dataset. ```{r filters} filters = listFilters(ensembl) filters[1:5,] ``` *Attributes* define the values we are interested in to retrieve. For example we want to retrieve the gene symbols or chromosomal coordinates. The `listAttributes()` function displays all available attributes in the selected dataset. ```{r attributes} attributes = listAttributes(ensembl) attributes[1:5,] ``` The `getBM()` function is the main query function in `r Biocpkg("biomaRt")`. It has four main arguments: * `attributes`: is a vector of attributes that one wants to retrieve (= the output of the query). * `filters`: is a vector of filters that one wil use as input to the query. * `values`: a vector of values for the filters. In case multple filters are in use, the values argument requires a list of values where each position in the list corresponds to the position of the filters in the filters argument (see examples below). * `mart`: is an object of class `Mart`, which is created by the `useMart()` function. *Note: for some frequently used queries to Ensembl, wrapper functions are available: `getGene()` and `getSequence()`. These functions call the `getBM()` function with hard coded filter and attribute names.* Now that we selected a BioMart database and dataset, and know about attributes, filters, and the values for filters; we can build a `r Biocpkg("biomaRt")` query. Let's make an easy query for the following problem: We have a list of Affymetrix identifiers from the u133plus2 platform and we want to retrieve the corresponding EntrezGene identifiers using the Ensembl mappings. The u133plus2 platform will be the filter for this query and as values for this filter we use our list of Affymetrix identifiers. As output (attributes) for the query we want to retrieve the EntrezGene and u133plus2 identifiers so we get a mapping of these two identifiers as a result. The exact names that we will have to use to specify the attributes and filters can be retrieved with the `listAttributes()` and `listFilters()` function respectively. Let's now run the query: ```{r getBM1, echo=TRUE,eval=TRUE} affyids=c("202763_at","209310_s_at","207500_at") getBM(attributes=c('affy_hg_u133_plus_2', 'entrezgene'), filters = 'affy_hg_u133_plus_2', values = affyids, mart = ensembl) ``` # Examples of biomaRt queries In the sections below a variety of example queries are described. Every example is written as a task, and we have to come up with a `r Biocpkg("biomaRt")` solution to the problem. ## Annotate a set of Affymetrix identifiers with HUGO symbol and chromosomal locations of corresponding genes We have a list of Affymetrix hgu133plus2 identifiers and we would like to retrieve the HUGO gene symbols, chromosome names, start and end positions and the bands of the corresponding genes. The `listAttributes()` and the `listFilters()` functions give us an overview of the available attributes and filters and we look in those lists to find the corresponding attribute and filter names we need. For this query we'll need the following attributes: hgnc_symbol, chromsome_name, start_position, end_position, band and affy_hg_u133_plus_2 (as we want these in the output to provide a mapping with our original Affymetrix input identifiers. There is one filter in this query which is the affy_hg_u133_plus_2 filter as we use a list of Affymetrix identifiers as input. Putting this all together in the `getBM()` and performing the query gives: ```{r task1, echo=TRUE,eval=TRUE} affyids=c("202763_at","209310_s_at","207500_at") getBM(attributes = c('affy_hg_u133_plus_2', 'hgnc_symbol', 'chromosome_name', 'start_position', 'end_position', 'band'), filters = 'affy_hg_u133_plus_2', values = affyids, mart = ensembl) ``` ## Annotate a set of EntrezGene identifiers with GO annotation In this task we start out with a list of EntrezGene identiers and we want to retrieve GO identifiers related to biological processes that are associated with these entrezgene identifiers. Again we look at the output of `listAttributes()` and `listFilters()` to find the filter and attributes we need. Then we construct the following query: ```{r task2, echo=TRUE,eval=TRUE} entrez=c("673","837") goids = getBM(attributes = c('entrezgene', 'go_id'), filters = 'entrezgene', values = entrez, mart = ensembl) head(goids) ``` ## Retrieve all HUGO gene symbols of genes that are located on chromosomes 17,20 or Y, and are associated with specific GO terms The GO terms we are interested in are: **GO:0051330**, **GO:0000080**, **GO:0000114**, **GO:0000082**. The key to performing this query is to understand that the `getBM()` function enables you to use more than one filter at the same time. In order to do this, the filter argument should be a vector with the filter names. The values should be a list, where the first element of the list corresponds to the first filter and the second list element to the second filter and so on. The elements of this list are vectors containing the possible values for the corresponding filters. ```{r task3, echo=TRUE,eval=TRUE} go=c("GO:0051330","GO:0000080","GO:0000114","GO:0000082") chrom=c(17,20,"Y") getBM(attributes= "hgnc_symbol", filters=c("go_id","chromosome_name"), values=list(go, chrom), mart=ensembl) ``` ## Annotate set of idenfiers with INTERPRO protein domain identifiers In this example we want to annotate the following two RefSeq identifiers: **NM_005359** and **NM_000546** with INTERPRO protein domain identifiers and a description of the protein domains. ```{r task4, echo=TRUE,eval=TRUE} refseqids = c("NM_005359","NM_000546") ipro = getBM(attributes=c("refseq_mrna","interpro","interpro_description"), filters="refseq_mrna", values=refseqids, mart=ensembl) ipro ``` ## Select all Affymetrix identifiers on the hgu133plus2 chip and Ensembl gene identifiers for genes located on chromosome 16 between basepair 1100000 and 1250000. In this example we will again use multiple filters: *chromosome_name*, *start*, and *end* as we filter on these three conditions. Note that when a chromosome name, a start position and an end position are jointly used as filters, the BioMart webservice interprets this as return everything from the given chromosome between the given start and end positions. ```{r task5, eval = TRUE} getBM(attributes = c('affy_hg_u133_plus_2','ensembl_gene_id'), filters = c('chromosome_name','start','end'), values = list(16,1100000,1250000), mart = ensembl) ``` ## Retrieve all entrezgene identifiers and HUGO gene symbols of genes which have a "MAP kinase activity" GO term associated with it. The GO identifier for MAP kinase activity is **GO:0004707**. In our query we will use *go_id* as our filter, and *entrezgene* and *hgnc_symbol* as attributes. Here's the query: ```{r task6, echo=TRUE, eval = TRUE} getBM(attributes = c('entrezgene','hgnc_symbol'), filters = 'go_id', values = 'GO:0004707', mart = ensembl) ``` ## Given a set of EntrezGene identifiers, retrieve 100bp upstream promoter sequences All sequence related queries to Ensembl are available through the `getSequence()` wrapper function. `getBM()` can also be used directly to retrieve sequences but this can get complicated so using getSequence is recommended. Sequences can be retrieved using the `getSequence()` function either starting from chromosomal coordinates or identifiers. The chromosome name can be specified using the *chromosome* argument. The *start* and *end* arguments are used to specify *start* and *end* positions on the chromosome. The type of sequence returned can be specified by the *seqType* argument which takes the following values: * *cdna* * *peptide* for protein sequences * *3utr* for 3' UTR sequences * *5utr* for 5' UTR sequences * *gene_exon* for exon sequences only * *transcript_exon* for transcript specific exonic sequences only * *transcript_exon_intron* gives the full unspliced transcript, that is exons + introns * *gene_exon_intron* gives the exons + introns of a gene * *coding* gives the coding sequence only * *coding_transcript_flank* gives the flanking region of the transcript including the UTRs, this must be accompanied with a given value for the upstream or downstream attribute * *coding_gene_flank* gives the flanking region of the gene including the UTRs, this must be accompanied with a given value for the upstream or downstream attribute * *transcript_flank* gives the flanking region of the transcript exculding the UTRs, this must be accompanied with a given value for the upstream or downstream attribute * *gene_flank* gives the flanking region of the gene excluding the UTRs, this must be accompanied with a given value for the upstream or downstream attribute In MySQL mode the `getSequence()` function is more limited and the sequence that is returned is the 5' to 3'+ strand of the genomic sequence, given a chromosome, as start and an end position. This task requires us to retrieve 100bp upstream promoter sequences from a set of EntrzGene identifiers. The *type* argument in `getSequence()` can be thought of as the filter in this query and uses the same input names given by `listFilters()`. In our query we use entrezgene for the type argument. Next we have to specify which type of sequences we want to retrieve, here we are interested in the sequences of the promoter region, starting right next to the coding start of the gene. Setting the *seqType* to coding_gene_flank will give us what we need. The *upstream* argument is used to specify how many bp of upstream sequence we want to retrieve, here we'll retrieve a rather short sequence of 100bp. Putting this all together in `getSequence()` gives: ```{r task7, eval=TRUE} entrez=c("673","7157","837") getSequence(id = entrez, type="entrezgene", seqType="coding_gene_flank", upstream=100, mart=ensembl) ``` ## Retrieve all 5' UTR sequences of all genes that are located on chromosome 3 between the positions 185,514,033 and 185,535,839 As described in the provious task getSequence can also use chromosomal coordinates to retrieve sequences of all genes that lie in the given region. We also have to specify which type of identifier we want to retrieve together with the sequences, here we choose for entrezgene identifiers. ```{r task8, echo=TRUE,eval=TRUE} utr5 = getSequence(chromosome=3, start=185514033, end=185535839, type="entrezgene", seqType="5utr", mart=ensembl) utr5 ``` ## Retrieve protein sequences for a given list of EntrezGene identifiers In this task the type argument specifies which type of identifiers we are using. To get an overview of other valid identifier types we refer to the `listFilters()` function. ```{r task9, echo=TRUE, eval=TRUE} protein = getSequence(id=c(100, 5728), type="entrezgene", seqType="peptide", mart=ensembl) protein ``` ## Retrieve known SNPs located on the human chromosome 8 between positions 148350 and 148612 For this example we'll first have to connect to a different BioMart database, namely snp. ```{r task10, echo=TRUE, eval=TRUE} snpmart = useMart(biomart = "ENSEMBL_MART_SNP", dataset="hsapiens_snp") ``` The `listAttributes()` and `listFilters()` functions give us an overview of the available attributes and filters. From these we need: *refsnp_id*, *allele*, *chrom_start* and *chrom_strand* as attributes; and as filters we'll use: *chrom_start*, *chrom_end* and *chr_name*. Note that when a chromosome name, a start position and an end position are jointly used as filters, the BioMart webservice interprets this as return everything from the given chromosome between the given start and end positions. Putting our selected attributes and filters into getBM gives: ```{r task10b} getBM(attributes = c('refsnp_id','allele','chrom_start','chrom_strand'), filters = c('chr_name','start','end'), values = list(8,148350,148612), mart = snpmart) ``` ## Given the human gene TP53, retrieve the human chromosomal location of this gene and also retrieve the chromosomal location and RefSeq id of its homolog in mouse. The `getLDS()` (Get Linked Dataset) function provides functionality to link 2 BioMart datasets which each other and construct a query over the two datasets. In Ensembl, linking two datasets translates to retrieving homology data across species. The usage of getLDS is very similar to `getBM()`. The linked dataset is provided by a separate `Mart` object and one has to specify filters and attributes for the linked dataset. Filters can either be applied to both datasets or to one of the datasets. Use the listFilters and listAttributes functions on both `Mart` objects to find the filters and attributes for each dataset (species in Ensembl). The attributes and filters of the linked dataset can be specified with the attributesL and filtersL arguments. Entering all this information into `getLDS()` gives: ```{r getLDS} human = useMart("ensembl", dataset = "hsapiens_gene_ensembl") mouse = useMart("ensembl", dataset = "mmusculus_gene_ensembl") getLDS(attributes = c("hgnc_symbol","chromosome_name", "start_position"), filters = "hgnc_symbol", values = "TP53",mart = human, attributesL = c("refseq_mrna","chromosome_name","start_position"), martL = mouse) ``` # Using archived versions of Ensembl It is possible to query archived versions of Ensembl through `r Biocpkg("biomaRt")`. There are currently two ways to access archived versions. ## Using `archive = TRUE` First we list the available Ensembl archives by using the `listMarts()` function and setting the archive attribute to TRUE. Note that not all archives are available this way and it seems that recently this only gives access to few archives if you don't see the version of the archive you need please look at the 2nd way to access archives. ```{r archiveMarts1} listMarts(archive = TRUE) ``` Next we select the archive we want to use using the `useMart()` function, again setting the archive attribute to TRUE and giving the full name of the BioMart e.g. ensembl_mart_46. ```{r archiveMarts2, echo = TRUE, eval = TRUE} ensembl = useMart("ensembl_mart_46", dataset="hsapiens_gene_ensembl", archive = TRUE) ``` If you don't know the dataset you want to use could first connect to the BioMart using `useMart()` and then use the `listDatasets()` function on this object. After you selected the BioMart database and dataset, queries can be performed in the same way as when using the current BioMart versions. ## Accessing archives through specifying the archive host Use the website and go down the bottom of the page. Click on 'view in Archive' and select the archive you need. Copy the url and use that url as shown below to connect to the specified BioMart database. The example below shows how to query Ensembl 54. ```{r archiveMarts3, echo = TRUE, eval = TRUE} listMarts(host='may2009.archive.ensembl.org') ensembl54=useMart(host='may2009.archive.ensembl.org', biomart='ENSEMBL_MART_ENSEMBL') ensembl54=useMart(host='may2009.archive.ensembl.org', biomart='ENSEMBL_MART_ENSEMBL', dataset='hsapiens_gene_ensembl') ``` # Using a BioMart other than Ensembl To demonstrate the use of the `r Biocpkg("biomaRt")` package with non-Ensembl databases the next query is performed using the Wormbase ParaSite BioMart. In this example, we use the `listMarts()` function to find the name of the available marts, given the URL of Wormbase. We use this to connect to Wormbase BioMart, find and select the gene dataset, and print the first 6 available attributes and filters. Then we use a list of gene names as filter and retrieve associated transcript IDs and the transcript biotype. ```{r wormbase, echo=TRUE, eval=TRUE} listMarts(host = "parasite.wormbase.org") wormbase = useMart(biomart = "parasite_mart", host = "parasite.wormbase.org") listDatasets(wormbase) wormbase <- useDataset(mart = wormbase, dataset = "wbps_gene") head(listFilters(wormbase)) head(listAttributes(wormbase)) getBM(attributes = c("external_gene_id","ensembl_transcript_id","transcript_biotype"), filters="gene_name", values=c("unc-26","his-33"), mart=wormbase) ``` # biomaRt helper functions This section describes a set of `r Biocpkg("biomaRt")` helper functions that can be used to export FASTA format sequences, retrieve values for certain filters and exploring the available filters and attributes in a more systematic manner. ## exportFASTA The data.frames obtained by the getSequence function can be exported to FASTA files using the `exportFASTA()` function. One has to specify the data.frame to export and the filename using the file argument. ## Finding out more information on filters ### filterType Boolean filters need a value TRUE or FALSE in `r Biocpkg("biomaRt")`. Setting the value TRUE will include all information that fulfill the filter requirement. Setting FALSE will exclude the information that fulfills the filter requirement and will return all values that don't fulfill the filter. For most of the filters, their name indicates if the type is a boolean or not and they will usually start with "with". However this is not a rule and to make sure you got the type right you can use the function `filterType()` to investigate the type of the filter you want to use. ```{r filterType} filterType("with_affy_hg_u133_plus_2",ensembl) ``` ### filterOptions Some filters have a limited set of values that can be given to them. To know which values these are one can use the `filterOptions()` function to retrieve the predetermed values of the respective filter. ```{r filterOptions} filterOptions("biotype",ensembl) ``` If there are no predetermed values e.g. for the entrezgene filter, then `filterOptions()` will return the type of filter it is. And most of the times the filter name or it's description will suggest what values one case use for the respective filter (e.g. entrezgene filter will work with enterzgene identifiers as values) ## Attribute Pages For large BioMart databases such as Ensembl, the number of attributes displayed by the `listAttributes()` function can be very large. In BioMart databases, attributes are put together in pages, such as sequences, features, homologs for Ensembl. An overview of the attributes pages present in the respective BioMart dataset can be obtained with the `attributePages()` function. ```{r attributePages} pages = attributePages(ensembl) pages ``` To show us a smaller list of attributes which belong to a specific page, we can now specify this in the `listAttributes()` function. *The set of attributes is still quite long, so we use `head()` to show only the first few items here.* ```{r listAttributes} head(listAttributes(ensembl, page="feature_page")) ``` We now get a short list of attributes related to the region where the genes are located. # Local BioMart databases The `r Biocpkg("biomaRt")` package can be used with a local install of a public BioMart database or a locally developed BioMart database and web service. In order for `r Biocpkg("biomaRt")` to recognize the database as a BioMart, make sure that the local database you create has a name conform with ` database_mart_version ` where database is the name of the database and version is a version number. No more underscores than the ones showed should be present in this name. A possible name is for example ` ensemblLocal_mart_46 `. ## Minimum requirements for local database installation More information on installing a local copy of a BioMart database or develop your own BioMart database and webservice can be found on Once the local database is installed you can use `r Biocpkg("biomaRt")` on this database by: ```{r localCopy, eval = FALSE} listMarts(host="www.myLocalHost.org", path="/myPathToWebservice/martservice") mart=useMart("nameOfMyMart",dataset="nameOfMyDataset",host="www.myLocalHost.org", path="/myPathToWebservice/martservice") ``` For more information on how to install a public BioMart database see: http://www.biomart.org/install.html and follow link databases. # Using `select()` In order to provide a more consistent interface to all annotations in Bioconductor the `select()`, `columns()`, `keytypes()` and `keys()` have been implemented to wrap some of the existing functionality above. These methods can be called in the same manner that they are used in other parts of the project except that instead of taking a `AnnotationDb` derived class they take instead a `Mart` derived class as their 1st argument. Otherwise usage should be essentially the same. You still use `columns()` to discover things that can be extracted from a `Mart`, and `keytypes()` to discover which things can be used as keys with `select()`. ```{r columnsAndKeyTypes} mart <- useMart(dataset="hsapiens_gene_ensembl",biomart='ensembl') head(keytypes(mart), n=3) head(columns(mart), n=3) ``` And you still can use `keys()` to extract potential keys, for a particular key type. ```{r keys1} k = keys(mart, keytype="chromosome_name") head(k, n=3) ``` When using `keys()`, you can even take advantage of the extra arguments that are available for others keys methods. ```{r keys2} k = keys(mart, keytype="chromosome_name", pattern="LRG") head(k, n=3) ``` Unfortunately the `keys()` method will not work with all key types because they are not all supported. But you can still use `select()` here to extract columns of data that match a particular set of keys (this is basically a wrapper for `getBM()`). ```{r select} affy=c("202763_at","209310_s_at","207500_at") select(mart, keys=affy, columns=c('affy_hg_u133_plus_2','entrezgene'), keytype='affy_hg_u133_plus_2') ``` So why would we want to do this when we already have functions like `getBM()`? For two reasons: 1) for people who are familiar with select and it's helper methods, they can now proceed to use `r Biocpkg("biomaRt")` making the same kinds of calls that are already familiar to them and 2) because the select method is implemented in many places elsewhere, the fact that these methods are shared allows for more convenient programmatic access of all these resources. An example of a package that takes advantage of this is the `r Biocpkg("OrganismDbi")` package. Where several packages can be accessed as if they were one resource. # Session Info ```{r sessionInfo} sessionInfo() warnings() ```