[ensembl-dev] Ensembl REST API | GET eqtl/stable_id/:species/:stable_id

[Ramiro Magno]

Hi Devs,

I've got a couple of questions/suggestions about this
endpoint: eqtl/stable_id/:species/:stable_id.

Q1: Could you make the json output schema uniform across queries with
different optional parameter combinations for the same endpoint? Let me
explain what I mean.

This endpoint has 4 optional parameters, of which 3 are relevant for
defining the data obtained: statistic, tissue and variant_name.

In documented example:

https://rest.ensembl.org/eqtl/id/homo_sapiens/ENSG00000122435?variant_name=rs302759;statistic=p-value;tissue=Adipose_Subcutaneous;content-type=application/json

the 3 parameters are specified leading to a very specific response. If we
use fewer parameters we get a more comprehensive response not just in the
number of associations reported but also in the number of variables
returned. Let me illustrate.

Response after query with:

1. "variant_name", "statistic=beta" and "tissue": returns only "value" (the
beta value, that is.);
2. "variant_name", "statistic=p-value" and "tissue": returns "value" (the
p-value) and "minus_log10_p_value";
3. "variant_name" and "tissue": returns the beta value, the p-value and
"minus_log10_p_value";
4. "variant_name", "statistic=p-value": returns p-value ("value"), "tissue"
and "minus_log10_p_value";
5. "variant_name", "statistic=beta": returns beta ("value") and "tissue";
6. "variant_name" only: returns p-value ("value"), beta ("value"), "tissue"
and "minus_log10_p_value"; it also returns the accessory variable
"statistic" to help discriminate the two "value"s.
7. If we do not specify any of the 3 optional parameters: returns all
variables mentioned so far but also: "seq_region_start", "seq_region_end",
"seq_region_name", "display_consequence" and "snp".

My question, specifically, is why don't you always return all these
variables, regardless of the optional parameters passed? I can understand
reasons related to bandwidth and perhaps extra computation on the server
side but I find that it would be very beneficial on the user side. :)

Q2: The json output always separates the two statistics: p-value and beta;
you separate them as if they were respecting different observations.
However, I think they both pertain the same observation, i.e. the eQTL
association. p-value is the statistical significance statistic, and the
beta value is the effect size statistic. So would it not make more sense to
simply return the two variables, p-value and beta, under the same json data
object? I.e., instead of having them in separate json objects and using two
variables for each, i.e. "statistic" and "value"?

My apologies for the verbose email!

Thanks!

Best regards, RM
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ensembl.org/pipermail/dev_ensembl.org/attachments/20190911/8af40fb6/attachment.html>