biopython / biopython/biopython
Handling of multiple UIDs in Entrez ELink
- Dominant language
- Python
- Stars
- 5.2k
- Forks
- 1.9k
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 11
Description
The Elink utility processes the `id` URL parameter differently than the others. EPost, EFetch, and ESummary all accept multiple UIDs as a single comma-delimited string (e.g. `id=UID1,UID2,UID3`). `elink` accepts this format as well as multiple instances of the `id` parameter (e.g. `id=UID1&id=UID2&id=UID3`). These two formats yield different results, as described in ELink's [documentation](https://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.ELink).
Starting from this [base URL](https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?db=gene&dbfrom=protein&tool=biopython), this is the result with multiple `id` parameters (`id=15718680&id=157427902&id=119703751`):
```xml
protein
15718680
gene
protein_gene
3702
protein
157427902
gene
protein_gene
522311
protein
119703751
gene
protein_gene
16428
```
And this is the result with the IDs joined (`id=15718680%2C157427902%2C119703751`):
```xml
protein
15718680
119703751
157427902
gene
protein_gene
522311
16428
3702
```
As you can see, the second result doesn't tell you which protein UIDs correspond to which gene UIDs.
Previously the functions in `Bio.Entrez` would leave the `id` parameter unmodified in the dictionary passed to `urllib.parse.urlencode` to build the query string. If this value was a list it would result in a URL like the first example, if it was a string it would be like the second. Both formats are valid for `elink` and give different results. Note that passing a list to `epost`, `efetch`, and `esummary` would be accepted but create an improperly-formatted request.
My new PR #3432 allows for passing a list for the `id` keyword argument for `epost`, `efetch`, and `esummary`, which is then formatted appropriately in the URL. However with `elink` I have left the old behavior in place to avoid potentially breaking things. I am wondering if this is the correct choice, though. I don't know if anyone has actually been using the 2nd behavior or if there is any advantage to it. It might make things less confusing if all four tools processed this argument in the same way.
Also, if keeping this behavior is the correct choice, should there be better documentation explaining it?
Contributor guide
Assessment
This issue has not been assessed yet.