biomaRt/DESCRIPTION0000644000175100017510000000251612607322160014700 0ustar00biocbuildbiocbuildPackage: biomaRt Version: 2.26.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 Maintainer: Steffen Durinck Depends: methods Imports: utils, XML, RCurl, AnnotationDbi Suggests: annotate 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: 2015-10-14 00:40:16 UTC; biocbuild biomaRt/NAMESPACE0000644000175100017510000000106312607264574014423 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/R/0000755000175100017510000000000012607264574013405 5ustar00biocbuildbiocbuildbiomaRt/R/biomaRt.R0000644000175100017510000012352612607264574015136 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.biomart.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.biomart.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") } 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) 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=" ")) 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")) { 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){ 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 = "\"", 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.R0000644000175100017510000000105712607264573016445 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.R0000644000175100017510000000760712607264573016105 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/0000755000175100017510000000000012607322160014265 5ustar00biocbuildbiocbuildbiomaRt/build/vignette.rds0000644000175100017510000000033612607322160016626 0ustar00biocbuildbiocbuilduQ 0\}h)<K5MD#[vmUjM6;a `tq[b ss2#h>3bej9"I5шUOx!h*f䜃RQť*X٣2,{ NbƋy ¾5"՟$]Rmyң_3Zѝ*%|ޭ biomaRt/inst/0000755000175100017510000000000012607322160014143 5ustar00biocbuildbiocbuildbiomaRt/inst/CITATION0000644000175100017510000000342512607264574015322 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/0000755000175100017510000000000012607322160014710 5ustar00biocbuildbiocbuildbiomaRt/inst/doc/biomaRt.R0000644000175100017510000001744512607322160016443 0ustar00biocbuildbiocbuild### R code from vignette source 'biomaRt.Rnw' ################################################### ### code chunk number 1: annotate ################################################### ## library("annotate") options(width=120) ################################################### ### code chunk number 2: biomaRt ################################################### library("biomaRt") listMarts() ################################################### ### code chunk number 3: ensembl1 ################################################### ensembl=useMart("ensembl") ################################################### ### code chunk number 4: listDatasets ################################################### listDatasets(ensembl) ################################################### ### code chunk number 5: ensembl2 ################################################### ensembl = useMart("ensembl",dataset="hsapiens_gene_ensembl") ################################################### ### code chunk number 6: filters ################################################### filters = listFilters(ensembl) filters[1:5,] ################################################### ### code chunk number 7: attributes ################################################### attributes = listAttributes(ensembl) attributes[1:5,] ################################################### ### code chunk number 8: biomaRt.Rnw:120-122 (eval = FALSE) ################################################### ## 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) ################################################### ### code chunk number 9: biomaRt.Rnw:140-143 (eval = FALSE) ################################################### ## 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) ################################################### ### code chunk number 10: biomaRt.Rnw:158-161 (eval = FALSE) ################################################### ## entrez=c("673","837") ## goids = getBM(attributes=c('entrezgene','go_id'), filters='entrezgene', values=entrez, mart=ensembl) ## head(goids) ################################################### ### code chunk number 11: biomaRt.Rnw:197-199 (eval = FALSE) ################################################### ## refseqids = c("NM_005359","NM_000546") ## ipro = getBM(attributes=c("refseq_dna","interpro","interpro_description"), filters="refseq_dna",values=refseqids, mart=ensembl) ################################################### ### code chunk number 12: biomaRt.Rnw:221-223 ################################################### getBM(c('affy_hg_u133_plus_2','ensembl_gene_id'), filters = c('chromosome_name','start','end'), values=list(16,1100000,1250000), mart=ensembl) ################################################### ### code chunk number 13: biomaRt.Rnw:230-231 (eval = FALSE) ################################################### ## getBM(c('entrezgene','hgnc_symbol'), filters='go', values='GO:0004707', mart=ensembl) ################################################### ### code chunk number 14: biomaRt.Rnw:252-254 (eval = FALSE) ################################################### ## entrez=c("673","7157","837") ## getSequence(id = entrez, type="entrezgene",seqType="coding_gene_flank",upstream=100, mart=ensembl) ################################################### ### code chunk number 15: biomaRt.Rnw:262-265 (eval = FALSE) ################################################### ## utr5 = getSequence(chromosome=3, start=185514033, end=185535839, ## type="entrezgene",seqType="5utr", mart=ensembl) ## utr5 ################################################### ### code chunk number 16: biomaRt.Rnw:282-285 (eval = FALSE) ################################################### ## protein = getSequence(id=c(100, 5728),type="entrezgene", ## seqType="peptide", mart=ensembl) ## protein ################################################### ### code chunk number 17: biomaRt.Rnw:301-302 (eval = FALSE) ################################################### ## snpmart = useMart("snp", dataset="hsapiens_snp") ################################################### ### code chunk number 18: biomaRt.Rnw:309-310 (eval = FALSE) ################################################### ## getBM(c('refsnp_id','allele','chrom_start','chrom_strand'), filters = c('chr_name','chrom_start','chrom_end'), values = list(8,148350,148612), mart = snpmart) ################################################### ### code chunk number 19: biomaRt.Rnw:363-364 ################################################### listMarts(archive=TRUE) ################################################### ### code chunk number 20: biomaRt.Rnw:369-370 (eval = FALSE) ################################################### ## ensembl = useMart("ensembl_mart_46", dataset="hsapiens_gene_ensembl", archive = TRUE) ################################################### ### code chunk number 21: biomaRt.Rnw:381-384 (eval = FALSE) ################################################### ## 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') ################################################### ### code chunk number 22: biomaRt.Rnw:393-400 (eval = FALSE) ################################################### ## wormbase=useMart("WS220",dataset="wormbase_gene") ## listFilters(wormbase) ## listAttributes(wormbase) ## getBM(attributes = c("public_name","rnai","rnai_phenotype_phenotype_label"), ## filters="gene_name", values=c("unc-26","his-33"), ## mart=wormbase) ## ################################################### ### code chunk number 23: biomaRt.Rnw:432-433 ################################################### filterType("with_affy_hg_u133_plus_2",ensembl) ################################################### ### code chunk number 24: biomaRt.Rnw:442-443 ################################################### filterOptions("biotype",ensembl) ################################################### ### code chunk number 25: biomaRt.Rnw:458-460 ################################################### pages = attributePages(ensembl) pages ################################################### ### code chunk number 26: biomaRt.Rnw:467-468 ################################################### listAttributes(ensembl, page="feature_page") ################################################### ### code chunk number 27: columnsAndKeyTypes ################################################### mart<-useMart(dataset="hsapiens_gene_ensembl",biomart='ensembl') head(keytypes(mart), n=3) head(columns(mart), n=3) ################################################### ### code chunk number 28: keys1 ################################################### k = keys(mart, keytype="chromosome_name") head(k, n=3) ################################################### ### code chunk number 29: keys2 ################################################### k = keys(mart, keytype="chromosome_name", pattern="LRG") head(k, n=3) ################################################### ### code chunk number 30: 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') ################################################### ### code chunk number 31: biomaRt.Rnw:554-556 ################################################### sessionInfo() warnings() biomaRt/inst/doc/biomaRt.Rnw0000644000175100017510000007307012607322160017004 0ustar00biocbuildbiocbuild%\VignetteIndexEntry{The biomaRt users guide} %\VignetteDepends{biomaRt} %\VignetteKeywords{Annotation} %\VignettePackage{biomaRt} \documentclass[11pt]{article} \usepackage{hyperref} \usepackage{url} \usepackage[authoryear,round]{natbib} \bibliographystyle{plainnat} \newcommand{\scscst}{\scriptscriptstyle} \newcommand{\scst}{\scriptstyle} \newcommand{\Rfunction}[1]{{\texttt{#1}}} \newcommand{\Robject}[1]{{\texttt{#1}}} \newcommand{\Rpackage}[1]{{\textit{#1}}} \author{Steffen Durinck\footnote{durincks@gene.com}, Wolfgang Huber\footnote{huber@ebi.ac.uk}} \begin{document} \title{The biomaRt user's guide} \maketitle \tableofcontents %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{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 \Rpackage{biomaRt} package, provides an interface to a growing collection of databases implementing the BioMart software suite (\url{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 biomaRt users direct access to a diverse set of data and enable a wide range of powerful online queries from R. \section{Selecting a BioMart database and dataset} Every analysis with \Rpackage{biomaRt} starts with selecting a BioMart database to use. A first step is to check which BioMart web services are available. The function \Rfunction{listMarts} will display all available BioMart web services <>= ## library("annotate") options(width=120) @ \begin{scriptsize} <>= library("biomaRt") listMarts() @ \end{scriptsize} Note: if the function \Rfunction{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: \begin{verbatim} Sys.putenv("http\_proxy" = "http://my.proxy.org:9999") \end{verbatim} Some users have reported that the workaround above does not work, in this case an alternative proxy solution below can be tried: \begin{verbatim} options(RCurlOptions = list(proxy="uscache.kcc.com:80",proxyuserpwd="------:-------")) \end{verbatim} The \Rfunction{useMart} function can now be used to connect to a specified BioMart database, this must be a valid name given by \Rfunction{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 \Rfunction{listDatasets}. \begin{scriptsize} <>= listDatasets(ensembl) @ \end{scriptsize} To select a dataset we can update the \Robject{Mart} object using the function \Rfunction{useDataset}. In the example below we choose to use the hsapiens dataset. \begin{verbatim} ensembl = useDataset("hsapiens_gene_ensembl",mart=ensembl) \end{verbatim} 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") @ \section{How to build a biomaRt query} The \Rfunction{getBM} function has three arguments that need to be introduced: filters, attributes and values. \textit{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 \textit{chromosome\_name} can be used with value 'X'. The \Rfunction{listFilters} function shows you all available filters in the selected dataset.\\ <>= filters = listFilters(ensembl) filters[1:5,] @ \textit{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,] @ The \Rfunction{getBM} function is the main query function in biomaRt. It has four main arguments:\\ \begin{itemize} \item attributes: is a vector of attributes that one wants to retrieve (= the output of the query). \item filters: is a vector of filters that one wil use as input to the query. \item 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). \item mart: is and object of class \Robject{Mart}, which is created by the \Rfunction{useMart} function. \end{itemize} Note: for some frequently used queries to Ensembl, wrapper functions are available: \Rfunction{getGene} and \Rfunction{getSequence}. These functions call the \Rfunction{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 \Rfunction{listAttributes} and \Rfunction{listFilters} function respectively. Let's now run the query: \begin{scriptsize} <>= 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) @ \begin{verbatim} affy_hg_u133_plus_2 entrezgene 1 209310_s_at 837 2 207500_at 838 3 202763_at 836 \end{verbatim} \end{scriptsize} \section{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. \subsection{Task 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 \Rfunction{listAttributes} and the \Rfunction{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 \Rfunction{getBM} and performing the query gives: \begin{scriptsize} <>= 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) @ \begin{verbatim} affy_hg_u133_plus_2 hgnc_symbol chromosome_name start_position end_position band 1 209310_s_at CASP4 11 104813593 104840163 q22.3 2 207500_at CASP5 11 104864962 104893895 q22.3 3 202763_at CASP3 4 185548850 185570663 q35.1 \end{verbatim} \end{scriptsize} \subsection{Task 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 \Rfunction{listAttributes} and \Rfunction{listFilters} to find the filter and attributes we need. Then we construct the following query: \begin{scriptsize} <>= entrez=c("673","837") goids = getBM(attributes=c('entrezgene','go_id'), filters='entrezgene', values=entrez, mart=ensembl) head(goids) @ \begin{verbatim} entrezgene go_id 1 673 GO:0000186 2 673 GO:0006468 3 673 GO:0006916 4 673 GO:0007264 5 673 GO:0007268 \end{verbatim} \end{scriptsize} \subsection{Task 3: Retrieve all HUGO gene symbols of genes that are located on chromosomes 17,20 or Y ,\\ and are associated with one the following GO terms: \\"GO:0051330","GO:0000080","GO:0000114","GO:0000082"\\ (here we'll use more than one filter)} The \Rfunction{getBM} function enables you to use more than one filter. In this case 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. \begin{small} \begin{verbatim} go=c("GO:0051330","GO:0000080","GO:0000114") chrom=c(17,20,"Y") getBM(attributes= "hgnc_symbol", filters=c("go_id","chromosome_name"), values=list(go,chrom), mart=ensembl) \end{verbatim} \end{small} \begin{scriptsize} \begin{verbatim} hgnc_symbol 1 E2F1 \end{verbatim} \end{scriptsize} \subsection{Task 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_dna","interpro","interpro_description"), filters="refseq_dna",values=refseqids, mart=ensembl) @ \begin{scriptsize} \begin{verbatim} ipro refseq_dna interpro interpro_description 1 NM_000546 IPR002117 p53 tumor antigen 2 NM_000546 IPR010991 p53, tetramerisation 3 NM_000546 IPR011615 p53, DNA-binding 4 NM_000546 IPR013872 p53 transactivation domain (TAD) 5 NM_000546 IPR000694 Proline-rich region 6 NM_005359 IPR001132 MAD homology 2, Dwarfin-type 7 NM_005359 IPR003619 MAD homology 1, Dwarfin-type 8 NM_005359 IPR013019 MAD homology, MH1 \end{verbatim} \end{scriptsize} \subsection{Task 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. \begin{scriptsize} <<>>= getBM(c('affy_hg_u133_plus_2','ensembl_gene_id'), filters = c('chromosome_name','start','end'), values=list(16,1100000,1250000), mart=ensembl) @ \end{scriptsize} \subsection{Task 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 as filter and entrezgene and hgnc\_symbol as attributes. Here's the query: \begin{scriptsize} <>= getBM(c('entrezgene','hgnc_symbol'), filters='go', values='GO:0004707', mart=ensembl) @ \begin{verbatim} entrezgene hgnc_symbol 1 5601 MAPK9 2 225689 MAPK15 3 5599 MAPK8 4 5594 MAPK1 5 6300 MAPK12 \end{verbatim} \end{scriptsize} \subsection{Task 7: Given a set of EntrezGene identifiers, retrieve 100bp upstream promoter sequences} All sequence related queries to Ensembl are available through the \Rfunction{getSequence} wrapper function. \Rfunction{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 \Rfunction{getSequence} function either starting from chromosomal coordinates or identifiers. The chromosome name can be specified using the \textit{chromosome} argument. The \textit{start} and \textit{end} arguments are used to specify \textit{start} and \textit{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 \Rfunction{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.\\ Task 4 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 \Rfunction{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:\\ \begin{scriptsize} <>= entrez=c("673","7157","837") getSequence(id = entrez, type="entrezgene",seqType="coding_gene_flank",upstream=100, mart=ensembl) @ \end{scriptsize} \subsection{Task 8: Retrieve all 5' UTR sequences of all genes that are located on chromosome 3 between the positions 185514033 and 185535839} 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. \begin{scriptsize} <>= utr5 = getSequence(chromosome=3, start=185514033, end=185535839, type="entrezgene",seqType="5utr", mart=ensembl) utr5 @ \end{scriptsize} \begin{scriptsize} \begin{verbatim} V1 V2 .....GAAGCGGTGGC .... 1981 \end{verbatim} \end{scriptsize} \subsection{Task 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 \Rfunction{listFilters} function. \begin{scriptsize} <>= protein = getSequence(id=c(100, 5728),type="entrezgene", seqType="peptide", mart=ensembl) protein @ \end{scriptsize} \begin{scriptsize} \begin{verbatim} peptide entrezgene MAQTPAFDKPKVEL ... 100 MTAIIKEIVSRNKRR ... 5728 \end{verbatim} \end{scriptsize} \subsection{Task 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("snp", dataset="hsapiens_snp") @ The \Rfunction{listAttributes} and \Rfunction{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: \begin{scriptsize} <>= getBM(c('refsnp_id','allele','chrom_start','chrom_strand'), filters = c('chr_name','chrom_start','chrom_end'), values = list(8,148350,148612), mart = snpmart) @ \end{scriptsize} \begin{scriptsize} \begin{verbatim} refsnp_id allele chrom_start chrom_strand 1 rs1134195 G/T 148394 -1 2 rs4046274 C/A 148394 1 3 rs4046275 A/G 148411 1 4 rs13291 C/T 148462 1 5 rs1134192 G/A 148462 -1 6 rs4046276 C/T 148462 1 7 rs12019378 T/G 148471 1 8 rs1134191 C/T 148499 -1 9 rs4046277 G/A 148499 1 10 rs11136408 G/A 148525 1 11 rs1134190 C/T 148533 -1 12 rs4046278 G/A 148533 1 13 rs1134189 G/A 148535 -1 14 rs3965587 C/T 148535 1 15 rs1134187 G/A 148539 -1 16 rs1134186 T/C 148569 1 17 rs4378731 G/A 148601 1 \end{verbatim} \end{scriptsize} \subsection{Task 11: Given the human gene TP53, retrieve the human chromosomal location of this gene and also retrieve the chromosomal location and RefSeq id of it's homolog in mouse. } The \Rfunction{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 \Rfunction{getBM}. The linked dataset is provided by a separate \Robject{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 \Robject{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 \Rfunction{getLDS} gives: \begin{scriptsize} \begin{verbatim} 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_dna","chromosome_name","start_position"), martL = mouse) V1 V2 V3 V4 V5 V6 1 TP53 17 7512464 NM_011640 11 69396600 \end{verbatim} \end{scriptsize} \section{Using archived versions of Ensembl} It is possible to query archived versions of Ensembl through \Rpackage{biomaRt}. There are currently two ways to access archived versions. \subsection{Using the archive=TRUE } First we list the available Ensembl archives by using the \Rfunction{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. \begin{scriptsize} <<>>= listMarts(archive=TRUE) @ \end{scriptsize} Next we select the archive we want to use using the \Rfunction{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) @ If you don't know the dataset you want to use could first connect to the BioMart using \Rfunction{useMart} and then use the \Rfunction{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. \subsection{Accessing archives through specifying the archive host} Use the \url{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. \begin{scriptsize} <<>= 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') @ \end{scriptsize} \section{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 BioMart (WormMart). We connect to Wormbase, select the gene dataset to use and have a look at the available attributes and filters. Then we use a list of gene names as filter and retrieve associated RNAi identifiers together with a description of the RNAi phenotype. \begin{scriptsize} <>= wormbase=useMart("WS220",dataset="wormbase_gene") listFilters(wormbase) listAttributes(wormbase) getBM(attributes = c("public_name","rnai","rnai_phenotype_phenotype_label"), filters="gene_name", values=c("unc-26","his-33"), mart=wormbase) @ \end{scriptsize} \begin{scriptsize} \begin{verbatim} public_name rnai rnai_phenotype_phenotype_label 1 his-33 WBRNAi00082060 GRO slow growth 2 his-33 WBRNAi00082060 postembryonic development variant 3 his-33 WBRNAi00082060 EMB embryonic lethal 4 his-33 WBRNAi00082060 LVL larval lethal 5 his-33 WBRNAi00082060 LVA larval arrest 6 his-33 WBRNAi00082060 accumulated cell corpses \end{verbatim} \end{scriptsize} \section{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. \subsection{exportFASTA} The data.frames obtained by the getSequence function can be exported to FASTA files using the \Rfunction{exportFASTA} function. One has to specify the data.frame to export and the filename using the file argument. \subsection{Finding out more information on filters} \subsubsection{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 \Rfunction{filterType} to investigate the type of the filter you want to use. \begin{small} <<>>= filterType("with_affy_hg_u133_plus_2",ensembl) @ \end{small} \subsubsection{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 \Rfunction{filterOptions} function to retrieve the predetermed values of the respective filter. \begin{small} <<>>= filterOptions("biotype",ensembl) @ \end{small} If there are no predetermed values e.g. for the entrezgene filter, then \Rfunction{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) \subsection{Attribute Pages} For large BioMart databases such as Ensembl, the number of attributes displayed by the \Rfunction{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 \Rfunction{attributePages} function. \begin{small} <<>>= pages = attributePages(ensembl) pages @ \end{small} To show us a smaller list of attributes which belog to a specific page, we can now specify this in the \Rfunction{listAttributes} function as follows: \begin{small} <<>>= listAttributes(ensembl, page="feature_page") @ \end{small} We now get a short list of attributes related to the region where the genes are located. \section{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 \begin{verbatim} database_mart_version \end{verbatim} 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 \begin{verbatim} ensemblLocal_mart_46 \end{verbatim}. \subsection{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 \url{http://www.biomart.org} Once the local database is installed you can use biomaRt on this database by: \begin{scriptsize} \begin{verbatim} listMarts(host="www.myLocalHost.org", path="/myPathToWebservice/martservice") mart=useMart("nameOfMyMart",dataset="nameOfMyDataset",host="www.myLocalHost.org", path="/myPathToWebservice/martservice") \end{verbatim} \end{scriptsize} For more information on how to install a public BioMart database see: http://www.biomart.org/install.html and follow link databases. \section{Using \Rfunction{select}} In order to provide a more consistent interface to all annotations in Bioconductor the \Rfunction{select}, \Rfunction{columns}, \Rfunction{keytypes} and \Rfunction{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 \Robject{AnnotationDb} derived class they take instead a \Robject{Mart} derived class as their 1st argument. Otherwise usage should be essentially the same. You still use \Rfunction{columns} to discover things that can be extracted from a \Robject{Mart}, and \Rfunction{keytypes} to discover which things can be used as keys with \Rfunction{select}. <>= mart<-useMart(dataset="hsapiens_gene_ensembl",biomart='ensembl') head(keytypes(mart), n=3) head(columns(mart), n=3) @ And you still can use \Rfunction{keys} to extract potential keys, for a particular key type. <>= k = keys(mart, keytype="chromosome_name") head(k, n=3) @ When using \Rfunction{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) @ Unfortunately the \Rfunction{keys} method will not work with all key types because they are not all supported. But you can still use \Rfunction{select} here to extract columns of data that match a particular set of keys (this is basically a wrapper for \Rfunction{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') @ So why would we want to do this when we already have functions like \Rfunction{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 \Rpackage{OrganismDbi} package. Where several packages can be accessed as if they were one resource. \section{Session Info} <<>>= sessionInfo() warnings() @ \end{document}