https://github.com/sing-group/uniprot-id-mapping
UniProt ID Mapping in Java
https://github.com/sing-group/uniprot-id-mapping
Last synced: 23 days ago
JSON representation
UniProt ID Mapping in Java
- Host: GitHub
- URL: https://github.com/sing-group/uniprot-id-mapping
- Owner: sing-group
- License: mit
- Created: 2024-05-09T08:58:52.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-06-25T09:46:22.000Z (about 2 years ago)
- Last Synced: 2026-01-15T05:04:25.816Z (6 months ago)
- Language: Java
- Size: 33.2 KB
- Stars: 1
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Java API client for the UniProt ID Mapping service
This projet provides `uniprot-id-mapping`, a Java API client for the [UniProt ID Mapping service](https://www.uniprot.org/id-mapping/).
# Maven dependency
To include `uniprot-id-mapping` in your project, add our repository to the `pom.xml` first:
```xml
sing-maven-releases
SING Maven Releases
https://maven.sing-group.org/repository/maven-releases/
```
And then add the corresponding dependency:
```xml
org.sing_group
uniprot-id-mapping
1.0.0
```
# Use cases
## 1. Basic UniProt remote client
The core client is implemented by the `UniProtClient` class. It can be used as follows:
```java
UniProtClient client = new UniProtClient();
UniProtJob job = client.mapIds(
UniProtDbFrom.UNIPROTKB_AC_ID,
UniProtDbTo.GENEID,
"O77134", "P92177", "Q7KN62");
System.out.println("Job ID: " + job.getJobId());
System.out.println("Job status: " + job.getStatus());
if (job.getStatus().equals(JobStatus.FINISHED)) {
job.getResults().forEach((k, v) -> {
System.out.println(k + " -> " + v);
});
}
```
The `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.
## 2. Advanced remote client
The 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:
```java
IdCache cache = new PersistentIdCache("/tmp/cache.txt");
cache.addToCache("P92177", "12345", "67890");
UniProtBatchProcessor client = new UniProtBatchProcessor(2, new UniProtClient(), cache);
Map> results = client.mapIds(
UniProtDbFrom.UNIPROTKB_AC_ID,
UniProtDbTo.GENEID,
"O77134", "P92177", "Q7KN62"
);
results.forEach((k, v) -> {
System.out.println(k + " -> " + v + " (" + v.size() + ")");
});
```
The `UniProtBatchProcessor` constructor takes three arguments:
- `batchSize`: the maximum number of IDs in every single query. Larger lists will be divided in several queries.
- `client`: an `UniProtClient` instance.
- `cache`: an object that implements the `IdCache`. There are two implementations: `VolatileIdCache` and `PersistentIdCache`.
## 3. Local mapper
As 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:
```java
UniProtIdLocalMapper localMapper = new UniProtIdLocalMapper(
new File("src/test/resources/DROME_7227_idmapping_subset.dat"));
Map> results = localMapper.mapIds(
UniProtDbFrom.UNIPROTKB_AC_ID,
UniProtDbTo.GENEID,
"P32234", "P92177"
);
results.forEach((k, v) -> {
System.out.println(k + " -> " + v + " (" + v.size() + ")");
});
```
The `UniProtIdLocalMapper` constructor only takes a `.dat` file with the UniProt mapping data.
The 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:
| .dat file | enum constant |
|------------------------|-----------------------------------|
| EMBL-CDS | EMBL_GENBANK_DDBJ_CDS |
| EMBL | EMBL_GENBANK_DDBJ |
| EnsemblGenome_PRO | ENSEMBL_GENOMES_PROTEIN |
| EnsemblGenome_TRS | ENSEMBL_GENOMES_TRANSCRIPT |
| EnsemblGenome | ENSEMBL_GENOMES |
| Ensembl_PRO | ENSEMBL_PROTEIN |
| Ensembl_TRS | ENSEMBL_TRANSCRIPT |
| Ensembl | ENSEMBL |
| GI | GI_NUMBER |
| RefSeq | REFSEQ_PROTEIN |
| RefSeq_NT | REFSEQ_NUCLEOTIDE |
| Gene_ORFName | GENE_NAME |
| UniProtKB_AC-ID | UniProtDbFrom.UNIPROTKB_AC_ID |
| UniProtKB-ID | UniProtDbTo.UNIPROTKB |
Finally, 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.
### 3.1 Mapping versioned identifiers
Some 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`:
```java
UniProtIdLocalMapper localMapper = new UniProtIdLocalMapper(
new File("src/test/resources/MOUSE_10090_idmapping_subset.dat"),
true // Adds deversioned identifiers into the mappings
);
Map> results = localMapper.mapIds(
UniProtDbFrom.ENSEMBL,
UniProtDbTo.UNIPROTKB,
"ENSMUSG00000017843"
);
results.forEach((k, v) -> {
System.out.println(k + " -> " + v + " (" + v.size() + ")");
});
```