{"id":29224550,"url":"https://github.com/sing-group/uniprot-id-mapping","last_synced_at":"2026-06-30T19:32:07.243Z","repository":{"id":238994715,"uuid":"798181594","full_name":"sing-group/uniprot-id-mapping","owner":"sing-group","description":"UniProt ID Mapping in Java","archived":false,"fork":false,"pushed_at":"2024-06-25T09:46:22.000Z","size":34,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2026-01-15T05:04:25.816Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sing-group.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-09T08:58:52.000Z","updated_at":"2024-12-30T06:19:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"b9edc3b4-9454-4b3a-b4fe-a9e3dc567aec","html_url":"https://github.com/sing-group/uniprot-id-mapping","commit_stats":null,"previous_names":["sing-group/uniprot-id-mapping"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/sing-group/uniprot-id-mapping","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sing-group%2Funiprot-id-mapping","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sing-group%2Funiprot-id-mapping/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sing-group%2Funiprot-id-mapping/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sing-group%2Funiprot-id-mapping/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sing-group","download_url":"https://codeload.github.com/sing-group/uniprot-id-mapping/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sing-group%2Funiprot-id-mapping/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34981390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-03T06:07:15.751Z","updated_at":"2026-06-30T19:32:07.216Z","avatar_url":"https://github.com/sing-group.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Java API client for the UniProt ID Mapping service\n\nThis projet provides `uniprot-id-mapping`, a Java API client for the [UniProt ID Mapping service](https://www.uniprot.org/id-mapping/).\n\n# Maven dependency\n\nTo include `uniprot-id-mapping` in your project, add our repository to the `pom.xml` first:\n\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003esing-maven-releases\u003c/id\u003e\n        \u003cname\u003eSING Maven Releases\u003c/name\u003e\n        \u003curl\u003ehttps://maven.sing-group.org/repository/maven-releases/\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n```\n\nAnd then add the corresponding dependency:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.sing_group\u003c/groupId\u003e\n\t\u003cartifactId\u003euniprot-id-mapping\u003c/artifactId\u003e\n\t\u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n# Use cases\n\n## 1. Basic UniProt remote client\n\nThe core client is implemented by the `UniProtClient` class. It can be used as follows:\n\n```java\nUniProtClient client = new UniProtClient();\n\nUniProtJob job = client.mapIds(\n        UniProtDbFrom.UNIPROTKB_AC_ID,\n        UniProtDbTo.GENEID,\n        \"O77134\", \"P92177\", \"Q7KN62\");\n\nSystem.out.println(\"Job ID: \" + job.getJobId());\nSystem.out.println(\"Job status: \" + job.getStatus());\nif (job.getStatus().equals(JobStatus.FINISHED)) {\n    job.getResults().forEach((k, v) -\u003e {\n        System.out.println(k + \" -\u003e \" + v);\n    });\n}\n```\n\nThe `mapIds` method returns a `UniProtJob` instance that can be queried to retrieve job ID, job status and, when available, the mapping results. The source and target conversion databases are specified by enums `UniProtDbFrom` and `UniProtDbTo` respectively.\n\n## 2. Advanced remote client\n\nThe advanced client is implemented by the `UniProtBatchProcessor` class, which uses the `UniProtClient` internally to provide batch processing and allowing the use of a cache to avoid repeating queries. It can be used as follows:\n\n\n```java\nIdCache cache = new PersistentIdCache(\"/tmp/cache.txt\");\ncache.addToCache(\"P92177\", \"12345\", \"67890\");\n\nUniProtBatchProcessor client = new UniProtBatchProcessor(2, new UniProtClient(), cache);\n\nMap\u003cString, List\u003cString\u003e\u003e results = client.mapIds(\n    UniProtDbFrom.UNIPROTKB_AC_ID, \n    UniProtDbTo.GENEID,\n    \"O77134\", \"P92177\", \"Q7KN62\"\n);\n\nresults.forEach((k, v) -\u003e {\n    System.out.println(k + \" -\u003e \" + v + \" (\" + v.size() + \")\");\n});\n\n```\n\nThe `UniProtBatchProcessor` constructor takes three arguments:\n- `batchSize`: the maximum number of IDs in every single query. Larger lists will be divided in several queries.\n- `client`: an `UniProtClient` instance.\n- `cache`: an object that implements the `IdCache`. There are two implementations: `VolatileIdCache` and `PersistentIdCache`.\n\n## 3. Local mapper\n\nAs UniProt provides the underlying data files uing by the web service, the `UniProtIdLocalMapper` allows using them for mapping identifiers locally. It can be used as follows:\n\n```java\nUniProtIdLocalMapper localMapper = new UniProtIdLocalMapper(\n    new File(\"src/test/resources/DROME_7227_idmapping_subset.dat\"));\n\nMap\u003cString, List\u003cString\u003e\u003e results = localMapper.mapIds(\n    UniProtDbFrom.UNIPROTKB_AC_ID,\n    UniProtDbTo.GENEID,\n    \"P32234\", \"P92177\"\n);\n\nresults.forEach((k, v) -\u003e {\n    System.out.println(k + \" -\u003e \" + v + \" (\" + v.size() + \")\");\n});\n```\n\nThe `UniProtIdLocalMapper` constructor only takes a `.dat` file with the UniProt mapping data.\n\nThe database names in such `.dat` files are automatically mapped to `UniProtDbFrom` or `UniProtDbTo` when they have the same names than in the REST API. However, some names are different and are mapped directly, according to the following table:\n\n| .dat file              | enum constant                     |\n|------------------------|-----------------------------------|\n| EMBL-CDS               | EMBL_GENBANK_DDBJ_CDS             |\n| EMBL                   | EMBL_GENBANK_DDBJ                 |\n| EnsemblGenome_PRO      | ENSEMBL_GENOMES_PROTEIN           |\n| EnsemblGenome_TRS      | ENSEMBL_GENOMES_TRANSCRIPT        |\n| EnsemblGenome          | ENSEMBL_GENOMES                   |\n| Ensembl_PRO            | ENSEMBL_PROTEIN                   |\n| Ensembl_TRS            | ENSEMBL_TRANSCRIPT                |\n| Ensembl                | ENSEMBL                           |\n| GI                     | GI_NUMBER                         |\n| RefSeq                 | REFSEQ_PROTEIN                    |\n| RefSeq_NT              | REFSEQ_NUCLEOTIDE                 |\n| Gene_ORFName           | GENE_NAME                         |\n| UniProtKB_AC-ID        | UniProtDbFrom.UNIPROTKB_AC_ID     |\n| UniProtKB-ID           | UniProtDbTo.UNIPROTKB             |\n\nFinally, other DB names that appear in the file but do not have a correspondence to a known REST API database are ommitted. These are: EMDB, Gene_Synonym, MINT, and NCBI_TaxID.\n\n### 3.1 Mapping versioned identifiers\n\nSome identifiers include a version number. For instance, this happens with `ENSMUSG*` identifiers like `ENSMUSG00000017843.15`. When using the remote mapping, it is possible to map an identifier like `ENSMUSG00000017843` from `Ensemble` into `UniProtKB-ID` and obtain the corresponding hits (`Q60996`, `A0A1Y7VIR0` and `A0A1Y7VJC8` as of 25th June 2024). However, this identifier appears as `ENSMUSG00000017843.15` in the local mapping files. To make the `UniProtIdLocalMapper` behave like the remote mapper with such identifiers, a new constructor parameter was added in version `1.2.0`:\n\n```java\nUniProtIdLocalMapper localMapper = new UniProtIdLocalMapper(\n    new File(\"src/test/resources/MOUSE_10090_idmapping_subset.dat\"),\n    true // Adds deversioned identifiers into the mappings\n);\n\nMap\u003cString, List\u003cString\u003e\u003e results = localMapper.mapIds(\n    UniProtDbFrom.ENSEMBL,\n    UniProtDbTo.UNIPROTKB,\n    \"ENSMUSG00000017843\"\n);\n\nresults.forEach((k, v) -\u003e {\n    System.out.println(k + \" -\u003e \" + v + \" (\" + v.size() + \")\");\n});\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsing-group%2Funiprot-id-mapping","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsing-group%2Funiprot-id-mapping","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsing-group%2Funiprot-id-mapping/lists"}