Question about `/rest/trait/search` with `include_children=1`?

[ramiromagno]

Question about `/rest/trait/search` with `include_children=1`?

[smlmbrt]

Correct, but I think this is the ideal behaviour. The purpose of this endpoint is to find a list of traits that match your search terms/criteria, not to expose the structure of those terms in the ontology (parent/child relationships). For that it makes more sense to interrogate each term with the /rest/trait/{trait_id} endpoint.

The point of the include_children flag is to get EFO terms that might not have directly matching synonyms but are definitely related. For instance breast carcinoma (EFO_0000305) isn't returned in the /rest/trait/search?term=breast%20cancer&exact=0&include_children=0 query but is in the /rest/trait/search?term=breast%20cancer&exact=0&include_children=1 results because it doesn't have breast cancer as a synonym/label but it does have a parent with that term. In this way the behaviour of this endpoint makes sense as-is and wouldn't result in child terms being duplicated as results of the query and in the return of child terms in multiple parent terms.

Adding more of a description to the schema regarding its purpose is probably the best way to resolve this. Thoughts?

[ramiromagno]

Okay, thanks for the explanation Sam!

[smlmbrt]

No worries, this is the proposed change:

Search for Traits based on terms present in the ID, label, description synonyms, categories, or external mapped terms. The search term and filters for exact matching and child-term relationships can be included directly in the request URL, e.g.
https://www.pgscatalog.org/rest/trait/search?term=Alzheimer
This returns a list of Traits matching the search term (and by default their child terms from the ontology), including for each of them:

• Ontology ID, trait label, description and URL
• Trait categories
• Synonyms and external mapped terms
• Associated Polygenic Score(s)
• Associated Polygenic Score(s) with child trait(s)

This endpoint searches all traits in the database, including parent terms from the ontology that aren’t included in the /rest/trait/all endpoint.