Skip to content

Supported identifiers

You do not have to convert your files before uploading them. PaintOmics reads the first column of each data file as a feature name and looks that string up in the identifier tables it installed for your organism, then translates it into whatever identifier each pathway database is keyed on. This page says which strings it can recognise, how the translation works, and what to do when a file maps badly.

Two things are true of everything below, and it is worth reading them first.

  • Support varies by organism, and by server. The identifier types an organism accepts are whatever its installer actually built, and the pathway databases it can be analysed against are whatever that server installed for it. Nothing here is universal.
  • The mapping summary in Step 2 is the only authority for your own file. It reports, per omic and per database, how many of your features resolved. If this page and that card disagree about your organism, the card is right.

How a name becomes an identifier

Every gene-based omic goes through the same three steps when you press Run PaintOmics.

  1. Your string is looked up exactly as you typed it. The lookup does not filter on identifier type, so an Ensembl gene id, a UniProt accession and a gene symbol all go through the same query — and a column that mixes them works.
  2. The identifiers that name the same gene are collected, and among them PaintOmics takes the one the selected database is keyed on. That target is different for each database, and for KEGG it is different for each organism.
  3. If that fails, one further hop is tried, and only through gene-level identifiers: NCBI Gene ID, Ensembl gene id and KEGG gene id. Transcript and protein identifiers are deliberately excluded from this hop, because a shared peptide can join two paralogues — PaintOmics will not map your gene onto a family member to gain a match.

The gene-side match is literal

It is an exact, case-sensitive string comparison, and nothing is stripped. A versioned Ensembl id (ENSMUSG00000102693.2) is a different string from ENSMUSG00000102693 and matches nothing. If nothing at all maps, PaintOmics says so and, when it recognises version suffixes in your unmatched identifiers, tells you to strip them and run again. Metabolite names are the exception: they are matched case-insensitively (see Metabolites and other compound-based omics).

What each database is keyed on

Database Your features are translated into Where it is offered
KEGG The NCBI Gene ID for ten organisms; KEGG's own gene id for all the rest Every organism, always — the KEGG checkbox is ticked and disabled, and the server adds KEGG to every job whatever you submitted
Reactome Reactome's own gene identifier, which is an upper-cased gene symbol 15 of the 23 organisms configured in this release, where the server installed Reactome data for them
MapMan The MapMan gene identifier its bin mapping uses Arabidopsis, tomato, potato and rice
OmniPath A UniProt accession Human, mouse and rat only — the OmniPath web service serves no other organism

The organisms whose KEGG data is keyed on the NCBI Gene ID are human, mouse, rat, cow, pig, dog, chicken, chimpanzee, green anole and Xenopus tropicalis. Every other organism — including zebrafish, fruit fly, worm, both yeasts, Plasmodium, Dictyostelium and all the plants — is keyed on KEGG's own gene id, which spells a gene differently in each organism (Dmel_CG3068 for fly, CELE_C17G1.7 for worm, Os01g0147900 for rice under the RAP-DB code). You never have to type these yourself; they are the target of the translation, not an input requirement.

An organism that has no identifier configuration at all is offered KEGG and nothing else, even if pathways from another database are sitting in its database — a source whose identifiers cannot be mapped would contribute pathways that stay permanently empty, so it is not offered.

Which databases you actually see

Step 1 asks the server which databases are installed for the organism you picked, ticks those, and disables the rest with a not installed tag. The answer is computed per organism from two facts: that database's pathways are loaded for that organism, and that organism has an identifier mapping for it. Changing the organism re-ticks and re-labels the row.

If that request fails, Step 1 offers every database and prints a note under the checkbox group saying so. A row where all four boxes are tickable is a degraded state, not a server that has everything.

What you can upload

The identifier types an organism accepts are decided by its build script. Each build step registers its own identifier types, and a step whose download was missing is skipped with a warning — the organism installs anyway, without those types.

Build step Identifier types it installs
KEGG mapping UniProt accession, NCBI Gene ID, KEGG gene id, KEGG gene symbol and its synonyms
Ensembl Ensembl gene, transcript and protein ids, and NCBI Gene ID
RefSeq accessions RefSeq RNA and protein accessions, curated and predicted
RefSeq gene symbols Gene symbols and their synonyms
UniProt UniProt accession and UniProt identifier
MapMan MapMan gene identifier
Reactome Reactome gene identifier
Identifier aliases Gene ids from another genome version, on the organisms that have a table of them: see below

Most installed organisms have no build script of their own. The source tree carries a bespoke build script for 23 organisms; every other organism is built by the default script, which runs the KEGG mapping, the Ensembl step when the organism has a registered Ensembl genebuild, and the identifier aliases when it has a table. Those organisms accept UniProt accessions, NCBI Gene IDs, KEGG gene ids and KEGG gene symbols with their synonyms, Ensembl ids with a registered genebuild, and a table's ids with a table — and nothing else: RefSeq accessions do not resolve. On the public server at paintomics.uv.es, which listed 133 organisms on 21 August 2026, that is about 110 of the list.

Organisms with an identifier configuration

These 23 organisms have an entry in the shipped identifier configuration. That entry is what names the target identifier for each database, so it is also what decides which databases the organism can be offered at all: an organism absent from it is offered KEGG and nothing else, and resolves through KEGG gene ids and KEGG gene symbols. Twenty-two of the 23 also have a build script of their own; the last column is what that script asks for, not a guarantee that every table came out populated — see the caveat under the table.

Organism Code Databases it can offer Build steps its install runs
Anolis carolinensis (green anole) acs KEGG Ensembl, RefSeq accessions, RefSeq symbols, UniProt
Arabidopsis thaliana ath KEGG, MapMan Ensembl, RefSeq accessions, RefSeq symbols, UniProt, KEGG mapping, MapMan
Bos taurus (cow) bta KEGG, Reactome Ensembl, RefSeq accessions, RefSeq symbols
Caenorhabditis elegans cel KEGG, Reactome Ensembl, RefSeq accessions, RefSeq symbols, UniProt, KEGG mapping
Canis lupus familiaris (dog) cfa KEGG, Reactome Ensembl, RefSeq accessions
Danio rerio (zebrafish) dre KEGG, Reactome Ensembl, RefSeq accessions, RefSeq symbols, UniProt, KEGG mapping — its Ensembl and RefSeq steps produced nothing, see below
Dictyostelium discoideum ddi KEGG, Reactome UniProt, KEGG mapping
Drosophila melanogaster (fruit fly) dme KEGG, Reactome Ensembl, RefSeq accessions, RefSeq symbols, UniProt, KEGG mapping
Gallus gallus (chicken) gga KEGG, Reactome Ensembl, RefSeq accessions, RefSeq symbols, UniProt
Homo sapiens (human) hsa KEGG, Reactome, OmniPath Ensembl, RefSeq accessions, RefSeq symbols, UniProt
Mus musculus (house mouse) mmu KEGG, Reactome, OmniPath Ensembl, RefSeq accessions, RefSeq symbols, UniProt
Oryza sativa japonica (rice) osa KEGG, MapMan KEGG mapping, MapMan
Oryza sativa japonica, RAP-DB identifiers dosa KEGG Ensembl, KEGG mapping — its Ensembl tables were registered and never filled, see below
Pan troglodytes (chimpanzee) ptr KEGG Ensembl, RefSeq accessions, RefSeq symbols
Plasmodium falciparum 3D7 pfa KEGG, Reactome RefSeq accessions, RefSeq symbols, KEGG mapping
Rattus norvegicus (rat) rno KEGG, Reactome, OmniPath Ensembl, RefSeq accessions, RefSeq symbols, UniProt
Saccharomyces cerevisiae (budding yeast) sce KEGG, Reactome Ensembl, RefSeq accessions, RefSeq symbols, UniProt, KEGG mapping
Schizosaccharomyces pombe (fission yeast) spo KEGG, Reactome UniProt, KEGG mapping
Solanum lycopersicum (tomato) sly KEGG, MapMan Ensembl, KEGG mapping, MapMan
Solanum tuberosum (potato) sot KEGG, MapMan KEGG mapping, MapMan
Sus scrofa (pig) ssc KEGG, Reactome Ensembl, RefSeq accessions, RefSeq symbols
Xenopus tropicalis (tropical clawed frog) xtr KEGG, Reactome Ensembl, RefSeq accessions, RefSeq symbols
Bifidobacterium animalis subsp. lactis BB-12 bbb KEGG KEGG mapping only — it has no build script of its own and is built by the default one

One organism is the other way round: mtu has a build script of its own but no identifier configuration, so it is offered KEGG alone and resolves like any default-built organism. Its script runs exactly what the default script runs — the KEGG mapping and the KEGG pathways — so it asks for nothing extra. The code is stale as well: the KEGG organism catalogue this release ships — the list Request an organism offers you — does not contain mtu, and names Mycobacterium tuberculosis H37Rv mtv.

bvu had a build script of its own too, and it was removed in September 2026. It installed GoMapMan's sugar beet export, but bvu is KEGG's code for the gut bacterium Phocaeicola vulgatus: GoMapMan's species codes are not KEGG codes, and this is one of the pairs where they disagree. So the build put 70 plant MapMan pathways and 27,421 sugar beet gene ids (RefBeet loci) into a bacterium, with no link to any of its KEGG genes. bvu is now built by the default script like any other bacterium: KEGG alone, no MapMan. There is no sugar beet MapMan either. KEGG's sugar beet is bvg, and neither NCBI Gene nor UniProt links a RefBeet id to one of its genes.

A build step can run and still install nothing

Some steps — the KEGG mapping, MapMan and Reactome — register their identifier types before they read their input files, so a missing or failed download leaves a type declared and empty; the others skip before registering and leave it absent altogether. Either way the lookup resolves without an error and maps nothing. Three cases are recorded in the configuration itself:

  • Zebrafish (dre) never got its Ensembl or RefSeq downloads, so it carries no Ensembl-derived NCBI Gene IDs and no RefSeq gene symbols even though its build script asks for both. Its KEGG identifiers and its gene symbols come from the KEGG mapping instead.
  • Rice under RAP-DB identifiers (dosa) carries an Ensembl transcript table its build registered and never filled, so nothing resolves through it. Its RAP-DB gene ids and its gene symbols come from the KEGG mapping instead.
  • Dog (cfa) builds no gene-symbol table at all. Uploading dog gene symbols maps nothing, and the names shown on painted boxes are the numeric gene ids rather than symbols.

This is exactly what the mapping summary exists to tell you for your own file. Run the job and read it before rewriting your identifiers.

Organisms outside this table can still be added. Any of the 11,550 organisms in the KEGG catalogue can be installed on request — use Request an organism under the organism field in Step 1 — and organisms KEGG does not cover can be installed from a gene-to-KO annotation. Newly installed organisms get the default identifier set unless someone writes a build script for them.

Gene ids from another genome version

Where a genome version renames its genes, an id from the other version matches nothing unless a source links them, even though the gene is there under its other name. Maize v4, pea Cameor v2 and grape 12X and PN40024.v4 ids now have tables that do, saying which installed gene each one names. Maize v4 is older than the v5 genes KEGG lists; pea Cameor v2 is newer than the v1a genome PaintOmics installs from Ensembl; grape 12X and v4 are older than the PN_T2T genome that KEGG and Ensembl list grape's genes on.

Organism Ids accepted Example How many reach a KEGG gene
Maize (Zea mays) B73 RefGen_v4 gene ids Zm00001d027230 About 27,800 of the 44,100 v4 genes
Pea (Pisum sativum, listed as Lathyrus oleraceus) Cameor v2 gene ids Psat.cameor.v2.0s1040g10400 About 22,000 of the 49,700 v2 genes
Grape (Vitis vinifera) 12X gene ids VIT_00s0125g00090 About 17,000 of the 29,900 12X protein-coding genes
PN40024.v4 gene ids Vitvi18g00828 About 8,200 of the 35,100 v4 protein-coding genes
NCBI locus tags VIT_00032725001 17,400

Why the others cannot map. KEGG lists maize and pea genes from one genome, so an id of another version maps only if something says which of those genes it is.

  • A maize v4 id maps when NCBI records its gene and KEGG lists that gene, or when MaizeGDB pairs it with exactly one gene of the current genome (v5) and that gene reaches KEGG. Of the other 16,400 or so, about 9,800 have no v5 gene in MaizeGDB's table and about 3,700 have one that reaches nothing in KEGG. About 1,600 point at several v5 genes, and PaintOmics will not guess among them. About 1,300 share one v5 gene with another v4 id and are left out by the strict 1:1 rule (about 470 of those genes reach KEGG). 29 more are left out because the sources put the id and the KEGG gene in different places on the genome: on another chromosome, on the same one but more than a megabase from where the current genome has the id (Zm00001d034536 names a gene 44 Mb away), or, for a MaizeGDB pair, at a gene that does not overlap the v5 gene MaizeGDB pairs it with. Where exactly one KEGG gene has the same protein as such an id and sits where the current genome has it, the id maps to that gene instead: 6 ids, Zm00001d012944 among them. The 29 left have no such gene, or the same protein in several places or in a place that disagrees (waxy 1's, for Zm00001d033937). These ids map nothing instead of risking a wrong gene.
  • A pea v2 id maps when the correspondence table published with the genome pairs it with a gene of the older v1a genome that reaches KEGG, or when its protein closely matches a protein of cultivar ZW6, the genome KEGG lists, each being the other's best match, and the genes around it that the table does pair put that ZW6 gene in the same place. The other 27,700 or so have neither, (12 of them) have both and the two disagree, or (221) match a ZW6 gene somewhere their neighbours do not put it.
  • A grape 12X or v4 id maps when Ensembl Plants, in the last release it annotated that version (52 for 12X, 60 for v4), linked the gene to exactly one NCBI gene that KEGG lists, and, where both are on a numbered chromosome, the genes around it on that version put the NCBI gene where KEGG has it. That leaves out about 12,900 12X genes and 26,900 v4 genes that Ensembl linked to no NCBI gene KEGG lists or to several, 67 ids whose neighbours put their NCBI gene elsewhere (VIT_05s0062g01430 and Vitvi05g01375, on chromosome 5 in both versions, were linked to a gene on chromosome 7), and eight 12X ids on a nuclear chromosome that were linked to a plastid or mitochondrial gene (VIT_13s0019g02630, on chromosome 13, to psbA). A locus tag maps when NCBI files a gene KEGG lists under it. Genoscope ids (GSVIVT00032725001), 12X.v2 ids (VIT_201s0011g00010) and UniProt's grape gene names have no table, because no source used here pairs them with an NCBI gene.

About 8,700 of the pea ids rest on a sequence match and its place

Of the 22,000 pea ids, about 13,200 come from the published table and about 8,700 from the comparison with ZW6, at 95 % identity or better over at least 80 % of both proteins, kept only where the neighbouring genes the table pairs put the ZW6 gene in the same place. That compares two cultivars. It says the protein is nearly the same and sits where that gene should, and not that anyone has shown the two are the same gene, so check a result that hangs on one of them.

Mapped does not mean on a pathway. Psat.cameor.v2.0s1040g10400 maps to KEGG gene 127107715, which KEGG lists and draws on no pathway, so it counts as mapped in Step 2 and paints nothing. These ids reach about 6,300 of KEGG's 9,700 maize pathway genes, about 5,200 of its 10,700 pea pathway genes and about 5,100 of its 6,300 grape pathway genes.

Transcript ids are not accepted. Zm00001d027230_T001, Psat.cameor.v2.1g306350.1, VIT_00s0125g00090.t01 and Vitvi18g00828_t001 stay unmapped, because only gene ids are in the tables. Remove the suffix (Zm00001d027230, Psat.cameor.v2.1g306350, VIT_00s0125g00090) and run again. That helps only genes the table covers.

Sorghum has a table as well, for a different reason. 3,192 of its 11,983 Ensembl genes with no link to KEGG now reach one through their NCBI record; the other 8,791 have no NCBI locus tag and still do not. Those 3,192 map whether you write SORBI_3001G262200 or the Phytozome spelling Sobic.001G262200.

These ids map on a server that has the tables, and an older installation may not. If a whole-genome file of protein-coding gene ids from one of these versions maps 0 % in Step 2, this server does not have the table yet. A short list can map 0 % on a server that has it, if every gene on it is one the table leaves out, and so does a file of maize lincRNA, tRNA or miRNA genes, none of which is in the table. Sorghum shows only a lower percentage, and transcript ids map 0 % either way.

The maize table is built from NCBI Gene and the MaizeGDB B73 gene cross-reference and gene models, the sorghum table from NCBI Gene. The pea table is built from Kreplak, Jonathan. Dataset from "A new genome assembly of the pea cultivar Cameor provides resources for functional genomics and genetics". Recherche Data Gouv, V1, 2025-04-01. doi:10.57745/5MDE99, under the Etalab Open Licence 2.0, described in Kreplak et al., Sci Data, 2026, and from the RefSeq proteins of cultivar ZW6 (NCBI assembly GCF_024323335.1). The grape table is built from NCBI Gene and from Ensembl Plants releases 52 and 60 (Yates et al., Ensembl 2026), which imposes no restrictions on the use of its data.

Metabolites and other compound-based omics

Compound-based omics are matched a different way, and identically whichever pathway databases you selected. There is no per-organism identifier table: your feature name is matched against PaintOmics' KEGG compound-name table.

  • Compound names are matched case-insensitively, as a substring. The name you type is escaped first, so NAD+ and (R)-lactate are read as literal text and not as patterns. If a name is generic enough to match more than 500 KEGG names — the default limit — the substring search is thrown away and only exact-name matches are kept.
  • KEGG compound ids work directly: C00002 is filed as a name of itself.
  • ChEBI ids work with or without the prefix — chebi:15422 and 15422 both find ATP.
  • A cell made only of punctuation (-, .) identifies nothing and is rejected rather than matched against every compound whose name contains that character.

Because a compound name is not unique — "D-Fructose" is the primary name of three different KEGG compounds — one uploaded name often matches several ids. Step 2 then raises a Compounds disambiguation card per ambiguous name, headed with how many there are (47 of them in the STATegra 5-omic example). Each card lists the candidates whose name closely matches what you uploaded, with the rest collapsed behind a N more matches link. Those close matches are ticked for you — where two of your input names claim the same KEGG compound, only the closer one keeps it. Untick what you did not measure and tick anything the card missed; only ticked compounds go into the analysis.

If the deployment has PaintOmics AI enabled and configured and you gave consent in Step 1, the card also offers Choose for me, which settles every ambiguous name at once and reports how many it changed by name and how many by PaintOmics AI, with an Undo that puts every tick back. Its answers are checked against each card's own candidate list, so it can only pick something that was already on the card. On a server without AI configured the panel does not appear at all.

Why an exact name match is not enough on its own

It would be wrong often enough to matter. "Alanine" is the literal name of C01401, the unspecified form, not of C00041 (L-alanine); "Serine" and "Malic acid" are each the literal name of two different KEGG compounds. So Choose for me settles a card without asking the model only when one candidate survives on the evidence — one close name match, or one that this organism actually draws on a pathway. Everything else goes to the model, and what the model is unsure of is left for you.

Regulatory and region-based omics

These two omic types are not matched by their own feature names.

  • A region-based omic (ChIP-seq, DNase-seq, ATAC-seq, Methyl-seq) is a BED file of coordinates plus a GTF annotation. PaintOmics associates regions with genes itself, and the gene identifiers it produces are whatever the GTF attribute named in GTF Tag for gene ID/name holds — gene_id unless you change it on the panel. If your GTF names genes by Ensembl id, that is what gets translated; a GTF whose gene_id is a locus tag the organism's tables do not carry will map poorly however good the regions are.
  • A regulatory omic (miRNA, transcription factors, methylation) carries a two-column associations file pairing each regulator with its target gene. The gene side is what is translated. The regulator name becomes the display label, and a symbol lookup is attempted for it: when that resolves, the canonical gene symbol is shown in its place. miRNA names normally miss, which is expected — the name you wrote is kept as you wrote it.

See Preparing your data for the file layouts and Regulatory omics (MORE) for what the regulatory analysis does with them.

Reading the mapping summary

Step 2 opens on Feature ID/name translation summary: the percentage of your input features that resolved into the identifier each database is keyed on. Beside it, when a job runs more than one database, Multiple databases used puts one row per omic and one column per database, so you can read across a row and compare one omic between databases.

The omic-by-database matching matrix in Step 2, one bar and count per database

One row per omic, one bar and count per database, with each database described underneath.

These figures are not a ranking. The databases use different identifier types and differ in scope by design, and a feature counts as soon as its name resolves, even if it belongs to no pathway in that database. Pathway coverage is reported later, in the enrichment table.

To see exactly which of your identifiers resolved and to what, use Download ID/Name mapping results under the translation summary. You get one zip per job holding, for every omic, a _matched.txt — your input name, the name and identifier it resolved to, which database it matched, your values and the relevance flags — and a _unmatched.txt listing everything that did not resolve. The same link is on Step 3 under Mapping and data statistics, but that card starts collapsed: press Show mapping in the toolbar first.

When a file maps poorly

Work through these in order.

  1. Check the organism. A human file run as mouse resolves almost nothing. This is the single most common cause.
  2. Check the first column for version suffixes. ENSMUSG00000102693.2 is not ENSMUSG00000102693. Strip the suffix and run again.
  3. Check that the identifier type is one the organism has. Consult the table above, then confirm against your own _unmatched.txt. For an organism built by the default script, gene symbols and KEGG gene ids are the safest choices; Ensembl ids resolve only where it has a registered Ensembl genebuild, and RefSeq accessions will not. An id from another version of the genome counts as another type where that version renames its genes, and it needs a table, as maize v4, pea Cameor v2 and grape 12X and v4 have.
  4. Look at which database is low, not just the total. A file that maps well to KEGG and badly to OmniPath is normal — OmniPath is keyed on UniProt accessions and covers a curated subset of signalling.
  5. Expect a metabolite file to look worse than a gene file. Names are matched against KEGG compound names; a house naming scheme, a lipid species name or an unannotated feature id has nothing to match. Uploading KEGG compound ids or ChEBI ids avoids the problem entirely.

If every gene-based omic maps to zero and no compound was selected either, PaintOmics stops when you continue from Step 2 and says so — naming the omic, how many identifiers it holds and a few of the ones that failed — rather than carrying an empty analysis forward.

If instead you see a message that the organism cannot translate identifiers for a database, that is a server configuration fault, not a problem with your file: the database's pathways are installed but the identifier table it is configured to use was never built. Report it to the administrators and run the job against another database in the meantime.

The AI input converter can repair a file whose format the analysis cannot read — the wrong delimiter, a spreadsheet with a header block, values in the wrong columns. It does not translate identifiers; that is what the mapping described on this page does.

See also