[ensembl-dev] Ensembl REST API | exact meaning of 'Species name'

[Brandon Walts]

Hi Ramiro

It's safest to use the "name" value for the validation you describe. 
That said, the REST endpoints should accept any of the aliases as well.

Regarding the meanings of "name", "scientific name", "display name", and 
"common name": "name" is the internal name used to uniquely identify a 
particular database. "Scientific name" is the name of the species, 
formatted with capitalisation and spacing for the website, and without a 
strain identifier (if any). Display names, likewise, are the names used 
for display on the website. Scientific, display, and common names are 
not suitable as species parameters because some of them contain 
characters that will not work in URLs (e.g. Mouse C57BL/6NJ), and they 
may not uniquely identify a database (e.g. species with multiple 
strains). "Human" works because there is an alias "human", and the 
lookup is case insensitive.

Aliases are assigned to each species by hand. Although some patterns are 
commonly seen, for example first letter of genus and first three letters 
of species ("ggor"), there is no systematic rule for creating aliases. 
This is partly due to the requirement that each alias be unique - having 
unique aliases that conform to a scheme simply can't scale. Because of 
those scaling issues, we are also no longer assigning aliases for new 
species (such as goat), although existing aliases will stay.

Best regards
-Brandon

On 18/07/2019 15:01, Ramiro Magno wrote:
> Hi Anja,
>
> May I ask for you help this previous question of mine about the 
> 'species' name?
>
> I am implementing a function in R that will (hopefully) do input 
> validation on the species name before placing requests on the server. 
> For that I need to know what are bona fide species names. So I thought 
> I'd get that info from the /info/species endpoint but I am not 
> entirely sure if I should use the 'name' or whether to allow any of 
> the other aliases...?
>
> I noticed that for some endpoints I can use 'human' or 'homo_sapiens' 
> interchangeably but I am not sure if other aliases will work for all 
> endpoints too. For example, the display name for human is 'Human' 
> (capital H) does that work too? There are also aliases like 'homo' or 
> 'hsap' will that work? I am looking for a rule that is applicable to 
> all species, not just human.
>
> Thank you again for your patience.
>
> RM
>
> On Wed, 17 Jul 2019 at 14:25, Ramiro Magno <ramiro.magno at gmail.com 
> <mailto:ramiro.magno at gmail.com>> wrote:
>
>     Hi
>
>     Several REST API endpoints use the parameter 'species' as a search
>     parameter. Typically, the description of this parameter reads
>     "Species name/alias", e.g., in
>     http://rest.ensembl.org/documentation/info/analysis.
>
>     My question is: what is the meaning of "Species name" here? I am
>     asking this because the endpoint
>     http://rest.ensembl.org/documentation/info/species gives me back a
>     list of species. In this list there are several fields related to
>     the species name:
>
>       (i) name, e.g. 'gorilla_gorilla';
>       (ii) aliases, e.g., "gorilla gorilla", "9595", "9593",
>     "gorilla", "gorgor", "gorilla_gorilla_gorilla", "ggor", "western
>     gorilla", "gorilla gorilla gorilla","ggorilla";
>       (iii) common_name, e.g. "Western Lowland Gorilla";
>       (iv) display_name, e.g. "Gorilla"
>
>     I've seen also the concept "Scientific name" in the Ensembl
>     website as well. Is this the same concept as 'name' aforementioned
>     in (i) but without the underscore ('_') and capitalised (is this a
>     fair assumption)?
>
>     BTW: What is a good database key for species? The 'taxon_id'
>     (returned by /info/species)?
>
>     Many thanks!
>
>     Ramiro Magno
>
>
> _______________________________________________
> Dev mailing list    Dev at ensembl.org
> Posting guidelines and subscribe/unsubscribe info: https://lists.ensembl.org/mailman/listinfo/dev_ensembl.org
> Ensembl Blog: http://www.ensembl.info/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ensembl.org/pipermail/dev_ensembl.org/attachments/20190718/815d13ae/attachment.html>