biomaRt 2.38.0
select()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.
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 94
## 2 ENSEMBL_MART_MOUSE Mouse strains 94
## 3 ENSEMBL_MART_SNP Ensembl Variation 94
## 4 ENSEMBL_MART_FUNCGEN Ensembl Regulation 94Note: 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
## 1 acalliptera_gene_ensembl Eastern happy genes (fAstCal1.2)
## 2 acarolinensis_gene_ensembl Anole lizard genes (AnoCar2.0)
## 3 acitrinellus_gene_ensembl Midas cichlid genes (Midas_v5)
## 4 amelanoleuca_gene_ensembl Panda genes (ailMel1)
## 5 amexicanus_gene_ensembl Cave fish genes (Astyanax_mexicanus-2.0)
## 6 anancymaae_gene_ensembl Ma's night monkey genes (Anan_2.0)
## 7 aocellaris_gene_ensembl Clown anemonefish genes (AmpOce1.0)
## 8 apercula_gene_ensembl Orange clownfish genes (Nemo_v1)
## 9 aplatyrhynchos_gene_ensembl Duck genes (BGI_duck_1.0)
## 10 apolyacanthus_gene_ensembl Spiny chromis genes (ASM210954v1)
## 11 atestudineus_gene_ensembl Climbing perch genes (fAnaTes1.1)
## 12 btaurus_gene_ensembl Cow genes (UMD3.1)
## 13 caperea_gene_ensembl Brazilian guinea pig genes (CavAp1.0)
## 14 catys_gene_ensembl Sooty mangabey genes (Caty_1.0)
## 15 ccapucinus_gene_ensembl Capuchin genes (Cebus_imitator-1.0)
## 16 cchok1gshd_gene_ensembl Chinese hamster CHOK1GS genes (CHOK1GS_HDv1)
## 17 ccrigri_gene_ensembl Chinese hamster CriGri genes (CriGri_1.0)
## 18 celegans_gene_ensembl Caenorhabditis elegans genes (WBcel235)
## 19 cfamiliaris_gene_ensembl Dog genes (CanFam3.1)
## 20 chircus_gene_ensembl Goat genes (ARS1)
## 21 choffmanni_gene_ensembl Sloth genes (choHof1)
## 22 cintestinalis_gene_ensembl C.intestinalis genes (KH)
## 23 cjacchus_gene_ensembl Marmoset genes (ASM275486v1)
## 24 clanigera_gene_ensembl Long-tailed chinchilla genes (ChiLan1.0)
## 25 cpalliatus_gene_ensembl Angola colobus genes (Cang.pa_1.0)
## 26 cporcellus_gene_ensembl Guinea Pig genes (Cavpor3.0)
## 27 csabaeus_gene_ensembl Vervet-AGM genes (ChlSab1.1)
## 28 csavignyi_gene_ensembl C.savignyi genes (CSAV 2.0)
## 29 csemilaevis_gene_ensembl Tongue sole genes (Cse_v1.0)
## 30 csyrichta_gene_ensembl Tarsier genes (Tarsius_syrichta-2.0.1)
## 31 cvariegatus_gene_ensembl Sheepshead minnow genes (C_variegatus-1.0)
## 32 dmelanogaster_gene_ensembl Fruitfly genes (BDGP6)
## 33 dnovemcinctus_gene_ensembl Armadillo genes (Dasnov3.0)
## 34 dordii_gene_ensembl Kangaroo rat genes (Dord_2.0)
## 35 drerio_gene_ensembl Zebrafish genes (GRCz11)
## 36 eburgeri_gene_ensembl Hagfish genes (Eburgeri_3.2)
## 37 ecaballus_gene_ensembl Horse genes (Equ Cab 2)
## 38 eeuropaeus_gene_ensembl Hedgehog genes (eriEur1)
## 39 elucius_gene_ensembl Northern pike genes (Eluc_V3)
## 40 etelfairi_gene_ensembl Lesser hedgehog tenrec genes (TENREC)
## 41 falbicollis_gene_ensembl Flycatcher genes (FicAlb_1.4)
## 42 fcatus_gene_ensembl Cat genes (Felis_catus_9.0)
## 43 fdamarensis_gene_ensembl Damara mole rat genes (DMR_v1.0)
## 44 fheteroclitus_gene_ensembl Mummichog genes (Fundulus_heteroclitus-3.0.2)
## 45 gaculeatus_gene_ensembl Stickleback genes (BROAD S1)
## 46 gaffinis_gene_ensembl Western mosquitofish genes (ASM309773v1)
## 47 ggallus_gene_ensembl Chicken genes (Gallus_gallus-5.0)
## 48 ggorilla_gene_ensembl Gorilla genes (gorGor4)
## 49 gmorhua_gene_ensembl Cod genes (gadMor1)
## 50 hburtoni_gene_ensembl Burton's mouthbrooder genes (AstBur1.0)
## 51 hcomes_gene_ensembl Tiger tail seahorse genes (H_comes_QL1_v1)
## 52 hfemale_gene_ensembl Naked mole-rat female genes (HetGla_female_1.0)
## 53 hmale_gene_ensembl Naked mole-rat male genes (HetGla_1.0)
## 54 hsapiens_gene_ensembl Human genes (GRCh38.p12)
## 55 ipunctatus_gene_ensembl Channel catfish genes (IpCoco_1.2)
## 56 itridecemlineatus_gene_ensembl Squirrel genes (SpeTri2.0)
## 57 jjaculus_gene_ensembl Lesser Egyptian jerboa genes (JacJac1.0)
## 58 kmarmoratus_gene_ensembl Mangrove rivulus genes (ASM164957v1)
## 59 lafricana_gene_ensembl Elephant genes (Loxafr3.0)
## 60 lbergylta_gene_ensembl Ballan wrasse genes (BallGen_V1)
## 61 lchalumnae_gene_ensembl Coelacanth genes (LatCha1)
## 62 loculatus_gene_ensembl Spotted gar genes (LepOcu1)
## 63 malbus_gene_ensembl Swamp eel genes (M_albus_1.0)
## 64 marmatus_gene_ensembl Zig-zag eel genes (fMasArm1.1)
## 65 mauratus_gene_ensembl Golden Hamster genes (MesAur1.0)
## 66 mcaroli_gene_ensembl Ryukyu mouse genes (CAROLI_EIJ_v1.1)
## 67 mdomestica_gene_ensembl Opossum genes (monDom5)
## 68 mfascicularis_gene_ensembl Crab-eating macaque genes (Macaca_fascicularis_5.0)
## 69 mfuro_gene_ensembl Ferret genes (MusPutFur1.0)
## 70 mgallopavo_gene_ensembl Turkey genes (Turkey_2.01)
## 71 mleucophaeus_gene_ensembl Drill genes (Mleu.le_1.0)
## 72 mlucifugus_gene_ensembl Microbat genes (Myoluc2.0)
## 73 mmola_gene_ensembl Ocean sunfish genes (ASM169857v1)
## 74 mmulatta_gene_ensembl Macaque genes (Mmul_8.0.1)
## 75 mmurinus_gene_ensembl Mouse Lemur genes (Mmur_3.0)
## 76 mmusculus_gene_ensembl Mouse genes (GRCm38.p6)
## 77 mnemestrina_gene_ensembl Pig-tailed macaque genes (Mnem_1.0)
## 78 mochrogaster_gene_ensembl Prairie vole genes (MicOch1.0)
## 79 mpahari_gene_ensembl Shrew mouse genes (PAHARI_EIJ_v1.1)
## 80 mspretus_gene_ensembl Algerian mouse genes (SPRET_EiJ_v1)
## 81 mzebra_gene_ensembl Zebra mbuna genes (M_zebra_UMD2a)
## 82 nbrichardi_gene_ensembl Lyretail cichlid genes (NeoBri1.0)
## 83 neugenii_gene_ensembl Wallaby genes (Meug_1.0)
## 84 ngalili_gene_ensembl Upper Galilee mountains blind mole rat genes (S.galili_v1.0)
## 85 nleucogenys_gene_ensembl Gibbon genes (Nleu_3.0)
## 86 oanatinus_gene_ensembl Platypus genes (OANA5)
## 87 oaries_gene_ensembl Sheep genes (Oar_v3.1)
## 88 ocuniculus_gene_ensembl Rabbit genes (OryCun2.0)
## 89 odegus_gene_ensembl Degu genes (OctDeg1.0)
## 90 ogarnettii_gene_ensembl Bushbaby genes (OtoGar3)
## 91 ohni_gene_ensembl Japanese Medaka HNI genes (ASM223471v1)
## 92 ohsok_gene_ensembl Japanese Medaka HSOK genes (ASM223469v1)
## 93 olatipes_gene_ensembl Japanese Medaka HdrR genes (ASM223467v1)
## 94 omelastigma_gene_ensembl Indian medaka genes (Om_v0.7.RACA)
## 95 oniloticus_gene_ensembl Tilapia genes (Orenil1.0)
## 96 oprinceps_gene_ensembl Pika genes (OchPri2.0-Ens)
## 97 pabelii_gene_ensembl Orangutan genes (PPYG2)
## 98 paltaica_gene_ensembl Tiger genes (PanTig1.0)
## 99 panubis_gene_ensembl Olive baboon genes (Panu_3.0)
## 100 pbairdii_gene_ensembl Northern American deer mouse genes (Pman_1.0)
## 101 pcapensis_gene_ensembl Hyrax genes (proCap1)
## 102 pcoquereli_gene_ensembl Coquerel's sifaka genes (Pcoq_1.0)
## 103 pformosa_gene_ensembl Amazon molly genes (Poecilia_formosa-5.1.2)
## 104 pkingsleyae_gene_ensembl Paramormyrops kingsleyae genes (PKINGS_0.1)
## 105 platipinna_gene_ensembl Sailfin molly genes (P_latipinna-1.0)
## 106 pmagnuspinnatus_gene_ensembl Big-finned mudskipper genes (PM.fa)
## 107 pmarinus_gene_ensembl Lamprey genes (Pmarinus_7.0)
## 108 pmexicana_gene_ensembl Shortfin molly genes (P_mexicana-1.0)
## 109 pnattereri_gene_ensembl Red-bellied piranha genes (Pygocentrus_nattereri-1.0.2)
## 110 pnyererei_gene_ensembl Pundamilia nyererei genes (PunNye1.0)
## 111 ppaniscus_gene_ensembl Bonobo genes (panpan1.1)
## 112 ppardus_gene_ensembl Leopard genes (PanPar1.0)
## 113 preticulata_gene_ensembl Guppy genes (Guppy_female_1.0_MT)
## 114 psinensis_gene_ensembl Chinese softshell turtle genes (PelSin_1.0)
## 115 ptroglodytes_gene_ensembl Chimpanzee genes (Pan_tro_3.0)
## 116 pvampyrus_gene_ensembl Megabat genes (pteVam1)
## 117 rbieti_gene_ensembl Black snub-nosed monkey genes (ASM169854v1)
## 118 rnorvegicus_gene_ensembl Rat genes (Rnor_6.0)
## 119 rroxellana_gene_ensembl Golden snub-nosed monkey genes (Rrox_v1)
## 120 saraneus_gene_ensembl Shrew genes (sorAra1)
## 121 sboliviensis_gene_ensembl Bolivian squirrel monkey genes (SaiBol1.0)
## 122 scerevisiae_gene_ensembl Saccharomyces cerevisiae genes (R64-1-1)
## 123 sdorsalis_gene_ensembl Yellowtail amberjack genes (Sedor1)
## 124 sdumerili_gene_ensembl Greater amberjack genes (Sdu_1.0)
## 125 sformosus_gene_ensembl Asian bonytongue genes (ASM162426v1)
## 126 sharrisii_gene_ensembl Tasmanian devil genes (Devil_ref v7.0)
## 127 smaximus_gene_ensembl Turbot genes (ASM318616v1)
## 128 spartitus_gene_ensembl Bicolor damselfish genes (Stegastes_partitus-1.0.2)
## 129 sscrofa_gene_ensembl Pig genes (Sscrofa11.1)
## 130 tbelangeri_gene_ensembl Tree Shrew genes (tupBel1)
## 131 tguttata_gene_ensembl Zebra Finch genes (taeGut3.2.4)
## 132 tnigroviridis_gene_ensembl Tetraodon genes (TETRAODON 8.0)
## 133 trubripes_gene_ensembl Fugu genes (FUGU5)
## 134 ttruncatus_gene_ensembl Dolphin genes (turTru1)
## 135 vpacos_gene_ensembl Alpaca genes (vicPac1)
## 136 xcouchianus_gene_ensembl Monterrey platyfish genes (Xiphophorus_couchianus-4.0.1)
## 137 xmaculatus_gene_ensembl Platyfish genes (X_maculatus-5.0-male)
## 138 xtropicalis_gene_ensembl Xenopus genes (JGI 4.2)
## version
## 1 fAstCal1.2
## 2 AnoCar2.0
## 3 Midas_v5
## 4 ailMel1
## 5 Astyanax_mexicanus-2.0
## 6 Anan_2.0
## 7 AmpOce1.0
## 8 Nemo_v1
## 9 BGI_duck_1.0
## 10 ASM210954v1
## 11 fAnaTes1.1
## 12 UMD3.1
## 13 CavAp1.0
## 14 Caty_1.0
## 15 Cebus_imitator-1.0
## 16 CHOK1GS_HDv1
## 17 CriGri_1.0
## 18 WBcel235
## 19 CanFam3.1
## 20 ARS1
## 21 choHof1
## 22 KH
## 23 ASM275486v1
## 24 ChiLan1.0
## 25 Cang.pa_1.0
## 26 Cavpor3.0
## 27 ChlSab1.1
## 28 CSAV 2.0
## 29 Cse_v1.0
## 30 Tarsius_syrichta-2.0.1
## 31 C_variegatus-1.0
## 32 BDGP6
## 33 Dasnov3.0
## 34 Dord_2.0
## 35 GRCz11
## 36 Eburgeri_3.2
## 37 Equ Cab 2
## 38 eriEur1
## 39 Eluc_V3
## 40 TENREC
## 41 FicAlb_1.4
## 42 Felis_catus_9.0
## 43 DMR_v1.0
## 44 Fundulus_heteroclitus-3.0.2
## 45 BROAD S1
## 46 ASM309773v1
## 47 Gallus_gallus-5.0
## 48 gorGor4
## 49 gadMor1
## 50 AstBur1.0
## 51 H_comes_QL1_v1
## 52 HetGla_female_1.0
## 53 HetGla_1.0
## 54 GRCh38.p12
## 55 IpCoco_1.2
## 56 SpeTri2.0
## 57 JacJac1.0
## 58 ASM164957v1
## 59 Loxafr3.0
## 60 BallGen_V1
## 61 LatCha1
## 62 LepOcu1
## 63 M_albus_1.0
## 64 fMasArm1.1
## 65 MesAur1.0
## 66 CAROLI_EIJ_v1.1
## 67 monDom5
## 68 Macaca_fascicularis_5.0
## 69 MusPutFur1.0
## 70 Turkey_2.01
## 71 Mleu.le_1.0
## 72 Myoluc2.0
## 73 ASM169857v1
## 74 Mmul_8.0.1
## 75 Mmur_3.0
## 76 GRCm38.p6
## 77 Mnem_1.0
## 78 MicOch1.0
## 79 PAHARI_EIJ_v1.1
## 80 SPRET_EiJ_v1
## 81 M_zebra_UMD2a
## 82 NeoBri1.0
## 83 Meug_1.0
## 84 S.galili_v1.0
## 85 Nleu_3.0
## 86 OANA5
## 87 Oar_v3.1
## 88 OryCun2.0
## 89 OctDeg1.0
## 90 OtoGar3
## 91 ASM223471v1
## 92 ASM223469v1
## 93 ASM223467v1
## 94 Om_v0.7.RACA
## 95 Orenil1.0
## 96 OchPri2.0-Ens
## 97 PPYG2
## 98 PanTig1.0
## 99 Panu_3.0
## 100 Pman_1.0
## 101 proCap1
## 102 Pcoq_1.0
## 103 Poecilia_formosa-5.1.2
## 104 PKINGS_0.1
## 105 P_latipinna-1.0
## 106 PM.fa
## 107 Pmarinus_7.0
## 108 P_mexicana-1.0
## 109 Pygocentrus_nattereri-1.0.2
## 110 PunNye1.0
## 111 panpan1.1
## 112 PanPar1.0
## 113 Guppy_female_1.0_MT
## 114 PelSin_1.0
## 115 Pan_tro_3.0
## 116 pteVam1
## 117 ASM169854v1
## 118 Rnor_6.0
## 119 Rrox_v1
## 120 sorAra1
## 121 SaiBol1.0
## 122 R64-1-1
## 123 Sedor1
## 124 Sdu_1.0
## 125 ASM162426v1
## 126 Devil_ref v7.0
## 127 ASM318616v1
## 128 Stegastes_partitus-1.0.2
## 129 Sscrofa11.1
## 130 tupBel1
## 131 taeGut3.2.4
## 132 TETRAODON 8.0
## 133 FUGU5
## 134 turTru1
## 135 vicPac1
## 136 Xiphophorus_couchianus-4.0.1
## 137 X_maculatus-5.0-male
## 138 JGI 4.2To 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")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/scaffold name
## 2 start Start
## 3 end End
## 4 band_start Band Start
## 5 band_end Band EndAttributes 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 Gene stable ID feature_page
## 2 ensembl_gene_id_version Gene stable ID version feature_page
## 3 ensembl_transcript_id Transcript stable ID feature_page
## 4 ensembl_transcript_id_version Transcript stable ID version feature_page
## 5 ensembl_peptide_id Protein stable ID feature_pageThe 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 202763_at 836
## 2 209310_s_at 837
## 3 207500_at 838The functions listDatasets(), listAttributes(), and listFilters() will return every available option for their respective types. However, this can be unwieldy when the list of results is long, involving much scrolling to find the entry you are interested in. biomaRt also provides the functions searchDatasets(), searchAttributes(), and searchFilters() which will try to find any entries matching a specific term or pattern. For example, if we want to find the details of any datasets in our ensembl mart that contain the term ‘hsapiens’ we could do the following:
searchDatasets(mart = ensembl, pattern = "hsapiens")## dataset description version
## 54 hsapiens_gene_ensembl Human genes (GRCh38.p12) GRCh38.p12You can search in a simlar fashion to find available attributes and filters that you may be interested in. The example below returns the details for all attributes that contain the pattern ‘hgnc’.
searchAttributes(mart = ensembl, pattern = "hgnc")## name description page
## 58 hgnc_id HGNC ID feature_page
## 59 hgnc_symbol HGNC symbol feature_page
## 60 hgnc_trans_name HGNC transcript name ID feature_pageFor advanced use, note that the pattern argument takes a regular expression. This means you can create more complex queries if required. Imagine, for example, that we have the string ENST00000577249.1, which we know is an Ensembl ID of some kind, but we aren’t sure what the appropriate filter term is. The example shown next uses a pattern that will find all filters that contain both the terms ‘ensembl’ and ‘id’. This allows use to reduced the list of filters to only those that might be appropriate for our example.
searchFilters(mart = ensembl, pattern = "ensembl.*id")## name description
## 54 ensembl_gene_id Gene stable ID(s) [e.g. ENSG00000000003]
## 55 ensembl_gene_id_version Gene stable ID(s) with version [e.g. ENSG00000000003.14]
## 56 ensembl_transcript_id Transcript stable ID(s) [e.g. ENST00000000233]
## 57 ensembl_transcript_id_version Transcript stable ID(s) with version [e.g. ENST00000000233.9]
## 58 ensembl_peptide_id Protein stable ID(s) [e.g. ENSP00000000233]
## 59 ensembl_peptide_id_version Protein stable ID(s) with version [e.g. ENSP00000000233.5]
## 60 ensembl_exon_id Exon ID(s) [e.g. ENSE00000327880]From this we can see that ENST00000577249.1 is a Trasncript ID with version, and the appropriate filter value to use with it is ensembl_transcript_id_version.
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.
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 202763_at CASP3 4 184627696 184649509 q35.1
## 2 209310_s_at CASP4 11 104942866 104969436 q22.3
## 3 207500_at CASP5 11 104994235 105023168 q22.3In 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 GO:0005622
## 2 673 GO:0046872
## 3 673 GO:0000166
## 4 673 GO:0004672
## 5 673 GO:0004674
## 6 673 GO:0005524The 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","chromosome_name"),
values=list(go, chrom), mart=ensembl)## hgnc_symbol
## 1 RPA1
## 2 CRLF3
## 3 CDC6
## 4 MCM8
## 5 CDK3
## 6 RPS6KB1In 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 superfamily
## 6 NM_000546 IPR013872 p53 transactivation domain
## 7 NM_000546 IPR036674 p53-like tetramerisation domain superfamily
## 8 NM_005359 IPR001132 SMAD domain, Dwarfin-type
## 9 NM_005359 IPR003619 MAD homology 1, Dwarfin-type
## 10 NM_005359 IPR008984 SMAD/FHA domain superfamily
## 11 NM_005359 IPR013019 MAD homology, MH1
## 12 NM_005359 IPR013790 Dwarfin
## 13 NM_005359 IPR017855 SMAD-like domain superfamily
## 14 NM_005359 IPR036578 SMAD MH1 domain superfamilyIn 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 205683_x_at ENSG00000197253
## 12 207134_x_at ENSG00000197253
## 13 217023_x_at ENSG00000197253
## 14 210084_x_at ENSG00000197253
## 15 215382_x_at ENSG00000197253
## 16 216474_x_at ENSG00000197253
## 17 205683_x_at ENSG00000172236
## 18 207134_x_at ENSG00000172236
## 19 217023_x_at ENSG00000172236
## 20 210084_x_at ENSG00000172236
## 21 215382_x_at ENSG00000172236
## 22 216474_x_at ENSG00000172236The 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',
values = 'GO:0004707',
mart = ensembl)## entrezgene hgnc_symbol
## 1 1432 MAPK14
## 2 5603 MAPK13
## 3 5594 MAPK1
## 4 5602 MAPK10
## 5 5595 MAPK3
## 6 5597 MAPK6
## 7 225689 MAPK15
## 8 5599 MAPK8
## 9 51701 NLK
## 10 5596 MAPK4
## 11 5601 MAPK9
## 12 5598 MAPK7
## 13 6300 MAPK12
## 14 5600 MAPK11All 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:
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 CACGTTTCCGCCCTTTGCAATAAGGAAATACATAGTTTACTTTCATTTTTGACTCTGAGGCTCTTTCCAACGCTGTAAAAAAGGACAGAGGCTGTTCCCT 837
## 2 TCCTTCTCTGCAGGCCCAGGTGACCCAGGGTTGGAAGTGTCTCATGCTGGATCCCCACTTTTCCTCTTGCAGCAGCCAGACTGCCTTCCGGGTCACTGCC 7157
## 3 CCTCCGCCTCCGCCTCCGCCTCCGCCTCCCCCAGCTCTCCGCCTCCCTTCCCCCTCCCCGCCCGACAGCGGCCGCTCGGGCCCCGGCTCTCGGTTATAAG 673As 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 ATTCTTGTGAATGTGACACACGATCTCTCCAGTTTCCAT
## 2 TGAGCAAAATCCCACAGTGGAAACTCTTAAGCCTCTGCGAAGTAAATCATTCTTGTGAATGTGACACACGATCTCTCCAGTTTCCAT
## 3 AGTCCCTAGGGAACTTCCTGTTGTCACCACACCTCTGAGTCGTCTGAGCTCACTGTGAGCAAAATCCCACAGTGGAAACTCTTAAGCCTCTGCGAAGTAAATCATTCTTGTGAATGTGACACACGATCTCTCCAGTTTCCAT
## 4 Sequence unavailable
## entrezgene
## 1 200879
## 2 200879
## 3 200879
## 4 200879In 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 Sequence unavailable
## 2 ALLFHKMMFETIPMFSGGTCNPQFVVCQLKVKIYSSNSGPTRREDKFMYFEFPQPLPVCGDIKVEFFHKQNKMLKKDKMFHFWVNTFFIPGPEETSEKVENGSLCDQEIDSICSIERADNDKEYLVLTLTKNDLDKANKDKANRYFSPNFKVS*
## 3 Sequence unavailable
## 4 LERGGEAAAAAAAAAAAPGRGSESPVTISRAGNAGELVSPLLLPPTRRRRRRHIQGPGPVLNLPSAAAAPPVARAPEAAGGGSRSEDYSSSPHSAAAAARPLAAEEKQAQSLQPSSSRRSSHYPAAVQSQAAAERGASATAKSRAISILQKKPRHQQLLPSLSSFFFSHRLPDMTAIIKEIVSRNKRRYQEDGFDLDLTYIYPNIIAMGFPAERLEGVYRNNIDDVVRFLDSKHKNHYKIYNLCAERHYDTAKFNCRVAQYPFEDHNPPQLELIKPFCEDLDQWLSEDDNHVAAIHCKAGKGRTGVMICAYLLHRGKFLKAQEALDFYGEVRTRDKKGVTIPSQRRYVYYYSYLLKNHLDYRPVALLFHKMMFETIPMFSGGTCNPQFVVCQLKVKIYSSNSGPTRREDKFMYFEFPQPLPVCGDIKVEFFHKQNKMLKKDKMFHFWVNTFFIPGPEETSEKVENGSLCDQEIDSICSIERADNDKEYLVLTLTKNDLDKANKDKANRYFSPNFKVKLYFTKTVEEPSNPEASSSTSVTPDVSDNEPDHYRYSDTTDSDPENEPFDEDQHTQITKV*
## 5 MTAIIKEIVSRNKRRYQEDGFDLDLTYIYPNIIAMGFPAERLEGVYRNNIDDVVRFLDSKHKNHYKIYNLCAERHYDTAKFNCRVAQYPFEDHNPPQLELIKPFCEDLDQWLSEDDNHVAAIHCKAGKGRTGVMICAYLLHRGKFLKAQEALDFYGEVRTRDKKGVTIPSQRRYVYYYSYLLKNHLDYRPVALLFHKMMFETIPMFSGGTCNPQFVVCQLKVKIYSSNSGPTRREDKFMYFEFPQPLPVCGDIKVEFFHKQNKMLKKDKMFHFWVNTFFIPGPEETSEKVENGSLCDQEIDSICSIERADNDKEYLVLTLTKNDLDKANKDKANRYFSPNFKVKLYFTKTVEEPSNPEASSSTSVTPDVSDNEPDHYRYSDTTDSDPENEPFDEDQHTQITKV*
## 6 MAQTPAFDKPKVELHVHLDGSIKPETILYYGRRRGIALPANTAEGLLNVIGMDKPLTLPDFLAKFDYYMPAIAGCREAIKRIAYEFVEMKAKEGVVYVEVRYSPHLLANSKVEPIPWNQAEGDLTPDEVVALVGQGLQEGERDFGVKARSILCCMRHQPNWSPKVVELCKKYQQQTVVAIDLAGDETIPGSSLLPGHVQAYQEAVKSGIHRTVHAGEVGSAEVVKEAVDILKTERLGHGYHTLEDQALYNRLRQENMHFEAQK*
## 7 MAQTPAFDKPKVELHVHLDGSIKPETILYYGRRRGIALPANTAEGLLNVIGMDKPLTLPDFLAKFDYYMPAIARL*
## 8 MAQTPAFDKPKVELHVHLDGSIKPETILYYGRRRGIALPANTAEGLLNVIGMDKPLTLPDFLAKFDYYMPAIAGCREAIKRIAYEFVEMKAKEGVVYVEVRYSPHLLANSKVEPIPWNQAEGDLTPDEVVALVGQGLQEGERDFGVKARSILCCMRHQPNWSPKVVELCKKYQQQTVVAIDLAGDETIPGSSLLPGHVQAYQAVDILKTERLGHGYHTLEDQALYNRLRQENMHFEICPWSSYLTGAWKPDTEHAVIRLKNDQANYSLNTDDPLIFKSTLDTDYQMTKRDMGFTEEEFKRLNINAAKSSFLPEDEKRELLDLLYKAYGMPPSASAGQNL*
## 9 MAQTPAFDKPKVELHVHLDGSIKPETILYYGRRRGIALPANTAEGLLNVIGMDKPLTLPDFLAKFDYYMPAIAGCREAIKRIAYEFVEMKAKEGVVYVEVRYSPHLLANSKVEPIPWNQAEGDLTPDEVVALVGQGLQEGERDFGVKARSILCCMRHQPNWSPKVVELCKKYQQQTVVAIDLAGDETIPGSSLLPGHVQAYQEAVKSGIHRTVHAGEVGSAEVVKEAVDILKTERLGHGYHTLEDQALYNRLRQENMHFEICPWSSYLTGAWKPDTEHAVIRLKNDQANYSLNTDDPLIFKSTLDTDYQMTKRDMGFTEEEFKRLNINAAKSSFLPEDEKRELLDLLYKAYGMPPSASAGQNL*
## entrezgene
## 1 5728
## 2 5728
## 3 100
## 4 5728
## 5 5728
## 6 100
## 7 100
## 8 100
## 9 100For 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 rs1450830176 G/C 148350 1
## 2 rs1360310185 C/T 148352 1
## 3 rs1434776028 A/T 148353 1
## 4 rs1413161474 C/T 148356 1
## 5 rs1410590268 A/G 148365 1
## 6 rs1193735780 T/A/C 148368 1
## 7 rs1409139861 C/T 148371 1
## 8 rs868546642 A/G 148372 1
## 9 rs547420070 A/C 148373 1
## 10 rs1236874674 C/T 148375 1
## 11 rs1207902742 C/T 148376 1
## 12 rs1437239557 T/C 148377 1
## 13 rs1160135941 T/G 148379 1
## 14 rs1229249227 A/T 148380 1
## 15 rs1328678285 C/G 148390 1
## 16 rs77274555 G/A/C 148391 1
## 17 rs567299969 T/A/C 148394 1
## 18 rs1457776094 A/C/G 148395 1
## 19 rs1292078334 C/T 148404 1
## 20 rs1456392146 A/T 148405 1
## 21 rs368076569 G/A 148407 1
## 22 rs1166604298 A/G 148408 1
## 23 rs1393545673 A/G/T 148410 1
## 24 rs1180076939 A/T 148413 1
## 25 rs1476313471 A/G 148414 1
## 26 rs1248424402 T/C 148417 1
## 27 rs1207939741 A/T 148419 1
## 28 rs1442232389 A/T 148421 1
## 29 rs1266518345 A/C 148424 1
## 30 rs1224022305 A/G 148426 1
## 31 rs1322431371 T/C 148427 1
## 32 rs1289196156 T/C 148429 1
## 33 rs1227114952 C/G 148433 1
## 34 rs1367904435 A/C 148436 1
## 35 rs1298979710 A/C 148440 1
## 36 rs1434874738 T/G 148441 1
## 37 rs1363439435 A/C 148443 1
## 38 rs1294944280 T/C 148453 1
## 39 rs1309134024 C/T 148454 1
## 40 rs1348796979 C/T 148460 1
## 41 rs1374829532 T/C 148461 1
## 42 rs1431088173 G/A 148462 1
## 43 rs1390780034 C/T 148468 1
## 44 rs1187817390 C/G 148470 1
## 45 rs1242396084 T/C 148471 1
## 46 rs1447487229 TT/- 148471 1
## 47 rs1193176841 A/G 148474 1
## 48 rs1488893482 C/T 148478 1
## 49 rs1264956600 T/A 148483 1
## 50 rs1219544655 A/G 148487 1
## 51 rs1344406365 CT/- 148495 1
## 52 rs745318437 C/G 148497 1
## 53 rs1321280897 G/T 148499 1
## 54 rs1220571972 C/T 148504 1
## 55 rs1228245996 G/T 148508 1
## 56 rs1340516169 C/G 148512 1
## 57 rs1263402165 C/T 148513 1
## 58 rs1303775291 C/G 148517 1
## 59 rs1387005982 C/A/T 148520 1
## 60 rs1291424168 T/A 148526 1
## 61 rs1411168240 T/C 148529 1
## 62 rs1370615124 C/T 148536 1
## 63 rs1469788925 T/C 148559 1
## 64 rs1214284488 T/C 148561 1
## 65 rs1237469667 G/T 148563 1
## 66 rs190721891 C/G 148576 1
## 67 rs1427698597 C/G 148594 1
## 68 rs1179966097 T/C 148595 1The 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.scaffold.name Gene.start..bp. RefSeq.mRNA.ID Chromosome.scaffold.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 69580359It is possible to query archived versions of Ensembl through biomaRt.
biomaRt provides the function listEnsemblArchives() to view the available archives. This function takes no arguments, and produces a table containing the names of the available archived versions, the date they were first available, and the URL where they can be accessed.
listEnsemblArchives()## name date url version current_release
## 1 Ensembl GRCh37 Feb 2014 http://grch37.ensembl.org GRCh37
## 2 Ensembl 94 Oct 2018 http://oct2018.archive.ensembl.org 94 *
## 3 Ensembl 93 Jul 2018 http://jul2018.archive.ensembl.org 93
## 4 Ensembl 92 Apr 2018 http://apr2018.archive.ensembl.org 92
## 5 Ensembl 91 Dec 2017 http://dec2017.archive.ensembl.org 91
## 6 Ensembl 90 Aug 2017 http://aug2017.archive.ensembl.org 90
## 7 Ensembl 89 May 2017 http://may2017.archive.ensembl.org 89
## 8 Ensembl 88 Mar 2017 http://mar2017.archive.ensembl.org 88
## 9 Ensembl 87 Dec 2016 http://dec2016.archive.ensembl.org 87
## 10 Ensembl 86 Oct 2016 http://oct2016.archive.ensembl.org 86
## 11 Ensembl 85 Jul 2016 http://jul2016.archive.ensembl.org 85
## 12 Ensembl 84 Mar 2016 http://mar2016.archive.ensembl.org 84
## 13 Ensembl 83 Dec 2015 http://dec2015.archive.ensembl.org 83
## 14 Ensembl 82 Sep 2015 http://sep2015.archive.ensembl.org 82
## 15 Ensembl 81 Jul 2015 http://jul2015.archive.ensembl.org 81
## 16 Ensembl 80 May 2015 http://may2015.archive.ensembl.org 80
## 17 Ensembl 79 Mar 2015 http://mar2015.archive.ensembl.org 79
## 18 Ensembl 78 Dec 2014 http://dec2014.archive.ensembl.org 78
## 19 Ensembl 77 Oct 2014 http://oct2014.archive.ensembl.org 77
## 20 Ensembl 76 Aug 2014 http://aug2014.archive.ensembl.org 76
## 21 Ensembl 75 Feb 2014 http://feb2014.archive.ensembl.org 75
## 22 Ensembl 74 Dec 2013 http://dec2013.archive.ensembl.org 74
## 23 Ensembl 67 May 2012 http://may2012.archive.ensembl.org 67
## 24 Ensembl 54 May 2009 http://may2009.archive.ensembl.org 54Alternatively, one can use the http://www.ensembl.org website to find archived version. From the main page scroll down the bottom of the page, click on ‘view in Archive’ and select the archive you need.
You will notice that there is an archive URL even for the current release of Ensembl. It can be useful to use this if you wish to ensure that script you write now will return exactly the same results in the future. Using www.ensembl.org will always access the current release, and so the data retrieved may change over time as new releases come out.
Whichever method you use to find the URL of the archive you wish to query, copy the url and use that in the host argument 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',
dataset='hsapiens_gene_ensembl')To demonstrate the use of the biomaRt package with non-Ensembl databases the next query is performed using the Wormbase ParaSite BioMart. Note that we use the https address and must provide the port as 443
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 Martwormbase = useMart(biomart = "parasite_mart",
host = "https://parasite.wormbase.org",
port = 443)
listDatasets(wormbase)## dataset description version
## 1 wbps_gene All Species (WBPS11) 11wormbase <- 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 Strandhead(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_pagegetBM(attributes = c("external_gene_id", "wbps_transcript_id", "transcript_biotype"),
filters="gene_name",
values=c("unc-26","his-33"),
mart=wormbase)## external_gene_id wbps_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_codingThis 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.
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.
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"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,rRNA_pseudogene,scaRNA,scRNA,sense_intronic,sense_overlapping,snoRNA,snRNA,sRNA,TEC,transcribed_processed_pseudogene,transcribed_unitary_pseudogene,transcribed_unprocessed_pseudogene,translated_processed_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)
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 Gene stable ID feature_page
## 2 ensembl_gene_id_version Gene stable ID version feature_page
## 3 ensembl_transcript_id Transcript stable ID feature_page
## 4 ensembl_transcript_id_version Transcript stable ID version feature_page
## 5 ensembl_peptide_id Protein stable ID feature_page
## 6 ensembl_peptide_id_version Protein stable ID version feature_pageWe now get a short list of attributes related to the region where the genes are located.
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.
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 202763_at 836
## 2 209310_s_at 837
## 3 207500_at 838So 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.
sessionInfo()## R version 3.5.1 Patched (2018-07-12 r74967)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 16.04.5 LTS
##
## Matrix products: default
## BLAS: /home/biocbuild/bbs-3.8-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.8-bioc/R/lib/libRlapack.so
##
## 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.38.0 BiocStyle_2.10.0
##
## loaded via a namespace (and not attached):
## [1] Rcpp_0.12.19 compiler_3.5.1 BiocManager_1.30.3 prettyunits_1.0.2 bitops_1.0-6
## [6] tools_3.5.1 progress_1.2.0 digest_0.6.18 bit_1.1-14 RSQLite_2.1.1
## [11] evaluate_0.12 memoise_1.1.0 pkgconfig_2.0.2 rlang_0.3.0.1 DBI_1.0.0
## [16] curl_3.2 yaml_2.2.0 parallel_3.5.1 xfun_0.4 httr_1.3.1
## [21] stringr_1.3.1 knitr_1.20 S4Vectors_0.20.0 IRanges_2.16.0 hms_0.4.2
## [26] stats4_3.5.1 rprojroot_1.3-2 bit64_0.9-7 Biobase_2.42.0 R6_2.3.0
## [31] AnnotationDbi_1.44.0 XML_3.98-1.16 rmarkdown_1.10 bookdown_0.7 blob_1.1.1
## [36] magrittr_1.5 backports_1.1.2 htmltools_0.3.6 BiocGenerics_0.28.0 assertthat_0.2.0
## [41] stringi_1.2.4 RCurl_1.95-4.11 crayon_1.3.4warnings()