# Ensembl BioMart Attributes: How to Interpret It In Ensembl BioMart, attributes are the columns of the table you export. Filters decide which genes, transcripts, or variants enter the table as rows, and attributes decide what each row contains. Ensembl BioMart is the bulk retrieval interface for the Ensembl genome annotation, the same data the [Ensembl genome browser](/blog/guides/ensembl-genome-browser) displays graphically. It answers table-shaped questions. Give me coordinates and symbols for every human protein-coding gene. Give me every mouse ortholog of these 500 human genes. Give me the peptide sequence for this transcript list. Access runs through a web form and a web service API, so the same query can be clicked together on the Ensembl website or scripted from R [1]. The Attributes panel is where most interpretation errors begin. Choose the wrong granularity and a request for 500 genes returns thousands of rows. Assume the wrong coordinate convention and every downstream interval operation shifts by one base. Treat a gene name as a unique key and database joins fail quietly. This article explains what attributes are, what the common attribute types actually report, how to read the output table, and how to verify your interpretation before an export reaches a pipeline. ## What Ensembl BioMart Attributes Mean Every BioMart query has three parts. The dataset is the database you query, for example Ensembl Genes 110 for human annotation or Ensembl Variation for polymorphism data. Filters restrict which entries enter the result. Attributes define the columns of the result table. A useful mental model comes from SQL, the standard database query language. Filters behave like a WHERE clause, attributes behave like a SELECT list, and the exported file is the result set. BioMart was built as a query-oriented access layer for large biological datasets, and that design has been adopted by resources well beyond Ensembl [1]. The web interface shows human-readable labels such as "Gene stable ID" and "Gene start (bp)". The web service and the biomaRt package in R use machine names for the same fields, such as ensembl_gene_id and start_position. Parentheses in a label carry units, so "Gene start (bp)" reports a position in base pairs. Machine names occasionally change between Ensembl releases, so any script that hardcodes them should refresh its attribute inventory after an upgrade. ### Attributes versus filters Filters and attributes answer different questions. Filters ask which entries, attributes ask what to know about them. A concrete example shows the split. Set the filters to chromosome 17 and gene type protein_coding. Set the attributes to Gene stable ID, Gene name, Gene start (bp), and Gene end (bp). The result is one row per protein-coding gene on chromosome 17 with four columns. Change the filters and you change which rows appear. Change the attributes and you change what those rows say. The distinction sounds trivial until a query returns twenty times more rows than expected, which almost always means an attribute, not a filter, changed the granularity. ### The attribute categories The Attributes panel organizes fields into pages, and each page groups fields that share a granularity. The page you draw from determines what one row means. The table below summarizes the main pages of the Ensembl Genes dataset. | Attribute page | Example attributes | What one row represents | Typical use | |, - |, - |, - |, - | | Gene | Gene stable ID, Gene start (bp), Gene end (bp), Gene name, Gene type | one gene | ID maps, genome-wide coordinate tables | | Transcript | Transcript stable ID, Transcript length, Transcript biotype | one transcript | transcript-level expression and annotation tables | | External | HGNC symbol, EntrezGene ID, UniProt/Swiss-Prot ID, RefSeq mRNA ID | one gene-to-external mapping | cross-database ID conversion | | Homologs | Mouse ortholog Ensembl ID, ortholog type, dN/dS, percent identity | one gene-ortholog pair | cross-species comparison | | Protein | Protein stable ID, Pfam domain ID, InterPro ID | one protein or protein-domain record | domain content surveys | | Sequences | cDNA sequence, peptide sequence, 5' upstream flank | one sequence record | FASTA for BLAST, primer design, database building | | Variation | Variant ID, allele, consequence type | one gene-variant link | annotation of variants affecting a gene list | Two cautions follow from the table. The External, Homologs, and Variation pages contain one-to-many mappings, so attributes from those pages multiply rows. The Sequences page changes the output format entirely, from a delimited table to FASTA text. ## How a BioMart Query Is Built, Step by Step ![Flow from dataset choice and filters through attributes, counting rows, export, and provenance, as the article's six numbered steps.](/article-images/illustrations/ensembl-biomart-attributes-query-build-steps.webp) Suppose the task is a table of all protein-coding genes on human chromosome 17 with curated symbols and GRCh38 coordinates. The workflow runs as follows. 1. Choose the dataset. The dropdown at the top of the interface lists Ensembl Genes, Ensembl Variation, and Ensembl Regulation for the current release, plus the Ensembl Genomes divisions for plants, fungi, protists, and non-vertebrate animals. Note the release number, because annotation changes between releases and the release number is part of the provenance of your table. 2. Set the filters. In the left panel, open the Region box and enter chromosome 17. Open the Gene box and restrict gene type to protein_coding. Filters can also take pasted identifier lists, which is how you turn a set of gene symbols or stable IDs into a row restriction. The web form suits lists of hundreds, and very large jobs belong in the web service. 3. Choose the attributes. In the right panel, the default selection returns stable IDs, coordinates, and names. Open the External page and add HGNC symbol. Keep Gene stable ID, Gene start (bp), and Gene end (bp) from the Gene page. The order in which you select attributes becomes the column order in the export. 4. Preview and count. The Results panel shows the first 10 rows of the table. The Count button reports the total number of rows the query will produce. Compare that number against expectation before exporting. If you filtered on 1,000 genes and the count says 4,000, some attribute expanded the rows. 5. Export. The Results panel offers TSV (tab-separated values), CSV, XLS, and HTML output, and can send results to Galaxy, an open web-based analysis platform. The interface can also generate the web service URL of the query, which encodes the dataset, filters, and attributes in one reproducible string. 6. Record the provenance. Save the release number, the query URL or the equivalent biomaRt code, and the export date. An attribute table without provenance is hard to defend six months later. ### Reading attribute names The same field appears under two names. The label is what the panel shows, and the machine name is what the web service and biomaRt accept. Common pairs include Gene stable ID with ensembl_gene_id, Gene start (bp) with start_position, Gene end (bp) with end_position, Gene type with gene_biotype, Chromosome/scaffold name with chromosome_name, and HGNC symbol with hgnc_symbol. In the XML query that the web service URL encodes, each selected attribute appears as an element carrying its machine name. When you read a colleague's biomaRt script, translate the machine names back to labels and the logic of the query becomes visible. ### What one row represents The most granular attribute you select sets the meaning of a row. With only Gene page attributes, one row is one gene. Add a Transcript attribute such as Transcript stable ID and one row becomes one transcript, so a gene with five annotated transcripts contributes five rows. Add exon attributes and one row becomes one exon. Add Gene Ontology (GO) terms, the controlled vocabulary of gene functions, and one row becomes one gene-term pair. Add mouse orthologs and one row becomes one gene-ortholog pair. The Count button reflects all of this, which is why counting before export is the cheapest quality check in the whole BioMart workflow. ## Interpreting the Core Attribute Types ### Stable identifiers and versions Ensembl stable IDs use fixed prefixes. ENSG marks a gene, ENST a transcript, ENSP a protein, and ENSE an exon. Non-human species add a species block, so mouse genes carry ENSMUSG prefixes. Human TP53 is ENSG00000141510. A version suffix after a period, for example ENSG00000141510.20, identifies a specific annotation state of that record, and the number increments when the record changes in a release. A change can be an altered exon structure, a sequence correction, or a merge with another record. The unversioned ID persists across releases even while the model behind it moves. Recent BioMart releases expose the stable ID and the version as separate columns, labeled Gene stable ID and Gene stable ID version. For reproducible work, store both together with the release number. When combining data from two releases, join on the unversioned ID and expect a small fraction of entries to have changed, or re-run the whole query against a single release through the archive sites. ### Coordinates, assembly, and strand ![Comparison of assembly, numbering, and strand conventions showing what each one changes and the error it causes when ignored.](/article-images/illustrations/ensembl-biomart-attributes-coordinate-conventions.webp) Three conventions govern the coordinate attributes, and each one generates a classic error. The first convention is the assembly. The main Ensembl site serves human data on GRCh38, the current [human reference genome](/knowledge/bioinformatics/human-reference-genomes-hg38-hg19-assemblies) assembly, while GRCh37 data lives on a dedicated site at grch37.ensembl.org. A coordinate is meaningless without its assembly, because the same base carries different numbers in different assemblies. Every coordinate column you export inherits the assembly of the dataset you queried, so record it once and keep every file in a project on the same assembly. The second convention is the numbering. BioMart coordinates are 1-based and fully closed. Gene start (bp) and Gene end (bp) both name bases that belong to the gene. BED files, a common format for genomic intervals, use 0-based half-open coordinates, so the same gene occupies a BED interval that starts one base lower. Converting BioMart output to BED means subtracting one from the start and leaving the end unchanged. GTF and GFF annotation files share the 1-based closed convention, so BioMart coordinates transfer to those formats without arithmetic. The third convention is the strand. BioMart reports strand as 1 or -1. On a gene with strand -1, Gene start (bp) is the lower genomic coordinate and the 3' end of the gene. The transcription start site sits at Gene end (bp), and the promoter lies at coordinates above it. TP53 illustrates the pattern. On GRCh38, TP53 occupies chromosome 17, positions 7,668,421 to 7,687,550, on the minus strand, so its transcription start site is at position 7,687,550 and upstream sequence lies beyond that number. The sequence flank attributes handle strand automatically, because 5' upstream flank is defined relative to the gene rather than to the chromosome. ### Gene names and external references Gene name reports the name Ensembl carries for the gene, which can be empty, provisional, or shared across a family. For human work, the HGNC symbol attribute reports the symbol curated by the HGNC nomenclature committee and is the better display label. Neither kind of name is a unique key. The stable ID is the key, and names are annotations attached to it. External attributes are mappings rather than intrinsic properties. UniProt/Swiss-Prot ID joins a gene to reviewed entries in the UniProt protein knowledgebase. RefSeq mRNA ID joins transcripts to NCBI RefSeq reference sequences. EntrezGene ID joins genes to NCBI's gene database. These joins are frequently one-to-many, because a gene can map to several UniProt entries through isoforms and mapping tables lag behind both databases. Adding external attributes can therefore duplicate rows, so export the mapping, inspect it, and decide per column whether you need one representative value or all of them. ### Homolog attributes The Homologs page adds columns for a chosen species, such as the mouse ortholog Ensembl ID, the associated gene name, the ortholog type, the dN/dS ratio, and percent identity. An ortholog is a gene in another species descended from the same ancestral gene. The type column carries the classification from Ensembl Compara, the Ensembl [comparative genomics](/blog/guides/comparative-genomics) resource. ortholog_one2one means a single human gene corresponds to a single mouse gene. ortholog_one2many means one human gene relates to several mouse genes. ortholog_many2many means the relationship is many-to-many in both directions. Every one2many and many2many link adds a row, so gene-level summaries require collapsing the table first, ideally with a documented rule for which ortholog you keep. dN/dS is the ratio of nonsynonymous to synonymous substitution rates, a standard comparative genomics measure. Values well below 1 indicate purifying selection on the coding sequence, and values near 1 indicate neutral evolution. Percent identity reports the raw similarity of the aligned sequences. Both statistics are properties of the ortholog pair, computed from the alignment, not of either gene alone. ### Gene Ontology attributes The GO attributes report GO term accession, GO term name, and GO domain. An accession looks like GO:0006915, the matching name is "apoptotic process", and the domain is one of biological_process, cellular_component, or molecular_function. Because a gene carries many GO terms, these attributes fan the table out to one row per gene-term pair, and a well-annotated gene can contribute dozens of rows. For per-gene analysis, aggregate the export to a unique set of accessions per gene. The annotation reflects what is curated in Ensembl, so absence of a GO term in your table is not evidence that a gene lacks the function. ### Sequence attributes and FASTA output Selecting any attribute on the Sequences page switches the export from a table to FASTA, the standard text format for nucleotide and protein sequences. The header line of each record carries the values of your other selected attributes, joined by pipes in the order you selected them. If you selected Gene stable ID, then Gene name, then the peptide sequence, the header reads >ENSG00000141510|TP53 and the sequence follows. Identifiers travel with the sequence only in that header, so choose them deliberately before exporting. Available sequence types include cDNA, coding sequence, peptide, exon sequences, unspliced gene sequence, and flanking sequence. The flank attributes take a user-specified length and respect strand, so the upstream flank of a minus-strand gene extends in the correct genomic direction from its transcription start site. Peptide exports feed proteomics pipelines directly. Mass spectrometry resources build on this kind of sequence retrieval, and PRIDE's Database on Demand tool exists to construct custom [protein sequence](/blog/guides/protein-sequence) databases that optimize search engine results [2]. ### Attributes in the Variation and Regulation datasets Switching the dataset changes the attribute vocabulary. In Ensembl Variation, filters select variants by identifier list, consequence type, or region, and attributes report the variant identifier, chromosome, position, alleles, consequence type, and, for coding variants, predictions from SIFT and PolyPhen, two tools that estimate the impact of amino acid changes. Consequence types use a controlled vocabulary shared with research and clinical annotation pipelines, with terms such as missense_variant and synonymous_variant. In Ensembl Regulation, attributes describe regulatory features, the cell types in which they were observed, and associated [transcription factor](/knowledge/molecular-biology/transcription-factor) binding. The interpretation rule stays the same across datasets. Read the attribute list of the mart you are querying, because the same word can mean different fields in different marts. ## Using Attributes in Practice ### The same attributes in biomaRt The biomaRt package speaks to the same BioMart service, so the web panel maps directly onto R code. The connection and the attribute inventory look like this. ```r library(biomaRt) ensembl <- useEnsembl(biomart = "genes", dataset = "hsapiens_gene_ensembl") attrs <- listAttributes(ensembl) head(attrs) ``` listAttributes returns a data frame with three columns. The name column holds the machine names that getBM accepts, the description column holds the human-readable labels from the web panel, and the page column records which attribute page each field belongs to. Searching that data frame is the scripted equivalent of browsing the panel, and it is the first thing to re-run after an Ensembl upgrade. A query mirroring the chromosome 17 example, restricted to one gene for clarity, looks like this. ```r tp53 <- getBM( attributes = c("ensembl_gene_id", "hgnc_symbol", "chromosome_name", "start_position", "end_position", "strand", "gene_biotype"), filters = "hgnc_symbol", values = "TP53", mart = ensembl ) ``` The result is a data frame with one row per matching gene and one column per attribute, named exactly as the attribute keys. Sequence retrieval uses the same interface by adding sequence attribute keys such as peptide to the attribute vector. To reproduce an older analysis, biomaRt can target the GRCh37 site and dated archive hosts, which pins both the attributes and the coordinates to the release you started from. ### Verifying an export before it reaches a pipeline Five checks catch most attribute errors in minutes. - Count before export. Press Count and compare the row total with the number of input identifiers. A filter of 500 symbols that counts 620 rows means some symbols matched multiple entries or an attribute expanded the rows. - Spot-check one known record. Take TP53 or another gene you know well, and compare the exported coordinates and strand against the Ensembl genome browser view of the same region and assembly. - Fix the join key now. Decide whether downstream joins use the unversioned stable ID, and strip versions consistently across every file in the project. - Keep the query. Save the web service URL or the biomaRt calls together with the release number. An export without its query is hard to reproduce and hard to audit. - State the assembly. Confirm that every coordinate file in the project documents GRCh38 or the relevant assembly, because coordinate columns carry no assembly label inside the table itself. ## BioMart, the Ensembl Genome Browser, and Other Data Sources ### When to use the browser instead of BioMart The Ensembl genome browser and BioMart expose the same annotation in different shapes. The browser is visual and regional. You search for TP53, land on the Location view, zoom into the region in detail, toggle tracks, and read exon structure, variants, and regulatory features off the screen. The browser's export tools handle the visible region well, and a typical Ensembl genome browser tutorial therefore teaches search, navigation, and track configuration first. BioMart is tabular and genome-wide. Use it when the deliverable is a file, such as an ID map, a coordinate table, a sequence set, or an ortholog table. A practical rule follows. If the question starts with "where" and "what does it look like", open the browser. If it starts with "how many" or "give me all", open BioMart. ### BioMart beyond Ensembl BioMart is a general access technology rather than an Ensembl feature. A case study of standard data access systems implemented BioMart, caBIG, and Google Data Sources over the same repository, PeptideAtlas, and reviewed each mechanism against common research use cases, finding that each suits particular uses with distinct tradeoffs [1]. The same study argues the broader principle that data projects serve their communities by offering several access routes, from web forms to programmatic interfaces, so each user can choose the simplest effective one [1]. Federated queries, meaning single queries that join several BioMart data stores, extend the attribute model across databases. A proteomics methods chapter describes using federated BioMart queries to integrate PRIDE identifications with resources such as Ensembl, Reactome, and UniProt [2]. When you cross marts, attribute interpretation stays local to each mart. An attribute in the PRIDE mart describes a peptide or protein observation, while an attribute in the Ensembl Genes mart describes a gene or transcript. Build the join after reading each mart's attribute list on its own terms. ## Misconceptions About Attributes - "Attributes are metadata about my query." They are the data columns you asked for. The query metadata lives in the URL, the release number, and your notes. - "One row equals one gene." Only when every selected attribute is gene-level. Transcript, exon, GO, ortholog, external, and variation attributes each raise the granularity. - "Gene start is where transcription starts." Only on plus-strand genes. On minus-strand genes the transcription start site sits at Gene end. - "A version bump means the gene moved." A version increment means the annotation record changed in some way, which may be structure, sequence, or merge history. Check the release notes before assuming a relocation. - "Gene name is a safe primary key." Names can be missing, duplicated, or reassigned between releases. Stable IDs exist precisely because names are not stable. - "BioMart coordinates drop into any tool unchanged." They drop into 1-based closed formats such as GTF. BED needs the one-base start adjustment, and mixing conventions shifts every interval. ## Common Mistakes and Limitations 1. Mixing assemblies in one project. Coordinates from GRCh37 and GRCh38 look equally plausible and are quietly incompatible. Pin the assembly at the dataset step and state it in every downstream file. 2. Ignoring row expansion. A gene-level table joined on stable ID fails after ortholog or GO attributes fan the rows out. Collapse or deduplicate with an explicit rule before joining. 3. Joining on names. Gene symbols and gene names change, collide, and go missing. Join on stable IDs and carry names along as display columns. 4. Handling versions inconsistently. One file with ENSG00000141510 and another with ENSG00000141510.20 will not join until versions are stripped or parsed the same way everywhere. 5. Forgetting the FASTA switch. A query with a sequence attribute returns FASTA, not a table, and the tabular attributes you selected live only in the header lines. Parse the headers deliberately. 6. Hardcoding attribute keys across releases. Machine names drift between Ensembl releases. Refresh listAttributes after every upgrade and fail loudly when a key disappears rather than silently returning an empty table. 7. Overloading the web form. The pasted-list filter suits hundreds of identifiers, not hundreds of thousands. Large jobs belong in the web service or in biomaRt, and complex interval questions belong in post-export tools such as bedtools or GenomicRanges. 8. Treating ortholog counts as gene counts. A one2many ortholog column makes per-gene statistics wrong unless you collapse first. Count genes before you add homolog attributes. 9. Expecting computation from a retrieval tool. BioMart retrieves annotation, it does not compute. Interval arithmetic, set operations, and statistics happen after export. Ensembl updates roughly every two to three months, so a table exported last quarter can differ from one exported today, which is accurate but only reproducible if the release is recorded. ## Quick Review - Attributes are output columns, filters are row restrictions, and the most granular attribute sets what one row means. - Stable IDs are the keys, versions mark annotation states, names are display labels. - Coordinates are 1-based closed and assembly-specific, strand is 1 or -1, and minus-strand genes place the transcription start site at Gene end. - External, homolog, GO, and variation attributes are one-to-many and expand rows. - Sequence attributes switch output to FASTA and move identifiers into pipe-joined headers. - Count before export, spot-check one known gene, and record the release, assembly, and query. - Attribute machine names can change between releases, so refresh the attribute list after upgrades. ## Frequently Asked Questions ### What does the Attributes panel in Ensembl BioMart do? It selects the columns of your export. Filters decide which rows appear, and attributes decide what each row carries, such as stable IDs, coordinates, names, sequences, GO terms, or orthologs. The panel is organized into pages, and the page you draw from determines what one row represents. ### Why does my BioMart export have more rows than the genes I filtered? Because at least one selected attribute is one-to-many. Transcript, exon, GO term, ortholog, external reference, and variant attributes each raise the granularity, so a gene with five transcripts or thirty GO terms contributes that many rows. Press Count before export and compare the total with your input list. ### What is the difference between Gene stable ID and Gene stable ID version? The stable ID identifies the record across releases, and the version identifies a specific annotation state of that record. ENSG00000141510 stays the same gene while ENSG00000141510.20 names a particular annotated state. Store both, plus the release number, for reproducibility. ### Are Ensembl BioMart coordinates 0-based or 1-based? They are 1-based and fully closed, so Gene start and Gene end both name bases inside the feature. BED files are 0-based with an exclusive end, so subtract one from the BioMart start when writing BED. GTF and GFF share the 1-based convention and need no adjustment. ### How do I get the same attributes in R using biomaRt? Connect with useEnsembl, list the fields with listAttributes, and retrieve with getBM. The name column of listAttributes gives the machine names getBM accepts, and getBM returns a data frame with one column per attribute. Sequence attributes such as peptide work in the same call. ### Can BioMart combine Ensembl data with other databases? Yes, through federated queries across marts. Published proteomics work uses federated BioMart queries to join PRIDE identifications with Ensembl, Reactome, and UniProt. Interpret each mart's attributes on its own terms before building the join, because the same field name can mean different things in different marts. ## Sources 1. [Interfaces to PeptideAtlas: a case study of standard data access systems.](https://pubmed.ncbi.nlm.nih.gov/22941959/) 2. [PRIDE and "Database on Demand" as valuable tools for computational proteomics.](https://pubmed.ncbi.nlm.nih.gov/21063943/)