BiomaRt, Bioconductor R package
The Bioconductor BiomaRt R package is a quick, easy and powerful way to access BioMart right from your R software terminal.
The following documention is using R 2.2 and Bioconductor version 3.1.
Summary
- How to install the Bioconductor BiomaRt R package
- Bioconductor BiomaRt R package documentation
- Bioconductor BiomaRt R examples with the Ensembl Gene mart
How to install the Bioconductor BiomaRt R package
First make sure you have installed the R software on your computer.
Then, run the following commands to install the Bioconductor BiomaRt R package:
if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager") BiocManager::install("biomaRt")
Bioconductor BiomaRt R package documentation
More information regarding the Bioconductor BiomaRt, R package and documentation can be found on the BiomaRt Bioconductor page.
Bioconductor BiomaRt R examples with the Ensembl Gene mart
listEnsembl & listDatasets
To get the list of all the Ensembl mart availables on the ensembl.org website, run the "listEnsembl" function:
> library(biomaRt) > listEnsembl() biomart version 1 ensembl Ensembl Genes 79 2 snp Ensembl Variation 79 3 regulation Ensembl Regulation 79
You can give an Ensembl archive version as a parameter to get the list of archived Ensembl marts, for example for the Ensembl GRCh37 or release 78 marts:
> listEnsembl("GRCh=37") biomart version 1 ensembl Ensembl Genes 2 snp Ensembl Variation 3 regulation Ensembl Regulation > listEnsembl(version=78) biomart version 1 ensembl Ensembl Genes 78 2 snp Ensembl Variation 78 3 regulation Ensembl Regulation 78
The "listDatasets" function will give you the list of all the species available (mart datasets) for a given mart:
> library(biomaRt) > ensembl = useEnsembl(biomart="ensembl") > head(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 lafricana_gene_ensembl Loxodonta africana genes (loxAfr3) loxAfr3 5 itridecemlineatus_gene_ensembl Ictidomys tridecemlineatus genes (spetri2) spetri2 6 choffmanni_gene_ensembl Choloepus hoffmanni genes (choHof1) choHof1
You can also use listDatasets with the Ensembl GRCh37 and archived marts:
> library(biomaRt) > grch37 = useEnsembl(biomart="ensembl",GRCh=37) > listDatasets(grch37)[31:35,] dataset description version 31 hsapiens_gene_ensembl Homo sapiens genes (GRCh37.p13) GRCh37.p13 32 mfuro_gene_ensembl Mustela putorius furo genes (MusPutFur1.0) MusPutFur1.0 33 tbelangeri_gene_ensembl Tupaia belangeri genes (tupBel1) tupBel1 34 ggallus_gene_ensembl Gallus gallus genes (Galgal4) Galgal4 35 xtropicalis_gene_ensembl Xenopus tropicalis genes (JGI4.2) JGI4.2 > ensembl78 = useEnsembl(biomart="ensembl",version=78) > listDatasets(ensembl78)[31:35,] dataset description version 31 mlucifugus_gene_ensembl Myotis lucifugus genes (myoLuc2) myoLuc2 32 hsapiens_gene_ensembl Homo sapiens genes (GRCh38) GRCh38 33 pformosa_gene_ensembl Poecilia formosa genes (PoeFor_5.1.2) PoeFor_5.1.2 34 mfuro_gene_ensembl Mustela putorius furo genes (MusPutFur1.0) MusPutFur1.0 35 tbelangeri_gene_ensembl Tupaia belangeri genes (tupBel1) tupBel1
useEnsembl
The "useEnsembl" function allow you to connect to a an ensembl website mart by specifying a BioMart and dataset parameters. For example, to connect to the Ensembl live gene mart human dataset (GRCh38):
> library(biomaRt) > ensembl = useEnsembl(biomart="ensembl", dataset="hsapiens_gene_ensembl")
To connect to the human dataset of the Ensembl GRCh37 or release 78 gene marts:
> library(biomaRt) > ensembl = useEnsembl(biomart="ensembl", dataset="hsapiens_gene_ensembl", GRCh=37) > ensembl = useEnsembl(biomart="ensembl", dataset="hsapiens_gene_ensembl", version=78)
listMarts, listDatasets and useMart for the Ensembl mirrors
You can connect to the following Ensembl mirrors using the listMarts, listDatasets and useMart functions:
- Ensembl US West: http://uswest.ensembl.org/index.html
- Ensembl US East: http://useast.ensembl.org/index.html
- Ensembl Asia: http://asia.ensembl.org/index.html
For example to connect to the Ensembl US West mirror:
> library(biomaRt) > listMarts(host="uswest.ensembl.org") biomart version 1 ENSEMBL_MART_ENSEMBL Ensembl Genes 79 2 ENSEMBL_MART_SNP Ensembl Variation 79 3 ENSEMBL_MART_FUNCGEN Ensembl Regulation 79 4 ENSEMBL_MART_VEGA Vega 59 5 pride PRIDE (EBI UK) > ensembl_us_west = useMart(biomart="ENSEMBL_MART_ENSEMBL", host="uswest.ensembl.org") > head(listDatasets(ensembl_us_west)) 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 lafricana_gene_ensembl Loxodonta africana genes (loxAfr3) loxAfr3 5 itridecemlineatus_gene_ensembl Ictidomys tridecemlineatus genes (spetri2) spetri2 6 choffmanni_gene_ensembl Choloepus hoffmanni genes (choHof1) choHof1
Please note that the useMart function will always require a biomart and host parameters when connecting to an Ensembl mirror website.
listFilters & listAttributes
The "listFilters" function will give you the list of available filters for a given mart and species:
> library(biomaRt) > ensembl = useEnsembl(biomart="ensembl", dataset="hsapiens_gene_ensembl") > head(listFilters(ensembl)) 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 6 marker_start Marker Start
The "listAttributes" function will give you the list of the available attributes for a given mart and species:
> library(biomaRt) > ensembl = useEnsembl(biomart="ensembl", dataset="hsapiens_gene_ensembl") > head(listAttributes(ensembl)) name description 1 ensembl_gene_id Ensembl Gene ID 2 ensembl_transcript_id Ensembl Transcript ID 3 ensembl_peptide_id Ensembl Protein ID 4 ensembl_exon_id Ensembl Exon ID 5 description Description 6 chromosome_name Chromosome Name
getBM
The "getBM" function allow you to build a BioMart query using a list of mart filters and attributes.
Example query: Fetch all the Ensembl gene, transcript IDs, HGNC symbols and chromosome locations located on the human chromosome 1
> library(biomaRt) > ensembl = useEnsembl(biomart="ensembl", dataset="hsapiens_gene_ensembl") > chr1_genes <- getBM(attributes=c('ensembl_gene_id', 'ensembl_transcript_id','hgnc_symbol','chromosome_name','start_position','end_position'), filters = 'chromosome_name', values ="1", mart = ensembl) > head(chr1_gene) ensembl_gene_id ensembl_transcript_id hgnc_symbol chromosome_name start_position end_position 1 ENSG00000231510 ENST00000443270 1 5086459 5090899 2 ENSG00000162444 ENST00000315901 RBP7 1 9997206 10016020 3 ENSG00000162444 ENST00000294435 RBP7 1 9997206 10016020 4 ENSG00000270171 ENST00000602640 1 7693124 7694844 5 ENSG00000225643 ENST00000412797 1 25581478 25590356 6 ENSG00000116497 ENST00000530710 S100PBP 1 32816767 32858879
Example query: Fetch Ensembl Gene, Transcript IDs, HGNC symbols and Uniprot Swissprot accessions mapped to the human Ensembl Gene ID "ENSG00000139618"
> library(biomaRt) > ensembl = useEnsembl(biomart="ensembl", dataset="hsapiens_gene_ensembl") > hgnc_swissprot <- getBM(attributes=c('ensembl_gene_id','ensembl_transcript_id','hgnc_symbol','uniprotswissprot'),filters = 'ensembl_gene_id', values = 'ENSG00000139618', mart = ensembl) > hgnc_swissprot ensembl_gene_id ensembl_transcript_id hgnc_symbol uniprot_swissprot 1 ENSG00000139618 ENST00000380152 BRCA2 P51587 2 ENSG00000139618 ENST00000528762 BRCA2 3 ENSG00000139618 ENST00000470094 BRCA2 4 ENSG00000139618 ENST00000544455 BRCA2 P51587