biopython / biopython/biopython

Handling of multiple UIDs in Entrez ELink

Open
#4,087 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.