Add definition of new filters

[sdelatorrep]

This is managed by a Beacon Scout led by Tim Beck.

[tb143]

@Tom-Shorter has been working on formalising the filters schema and will include it here when complete.

[Tom-Shorter]

Here's a link in swaggerhub to a slimmed down beacon draft 3 spec which describes the following 3 endpoints:

• /filtering_terms
• /datasets/{id}/filtering_terms
• /g_variants.

We have decided to exclude endpoints unrelated to the filter scout groups focus and left in g_variants as the sole example for a query endpoint to increase readability. We also have a complete draft3 version of the specification which will be made available once finalised.

Tim will be posting a more detailed description about the changes which have been made in an upcoming comment.

[tb143]

The three categories of filters:

ontologyFilters are terms from an ontology contained in a public repository such as the EBI’s OLS or NCBO’s BioPortal.

alphanumericFilters define rules of selection between field name and field value pairs.

customFilters are locally defined by a Beacon (e.g. not corresponding to known ontology terms).

There are two information endpoints relating to filters, /filtering_terms and /datasets/{id}/filtering_terms, the former providing information on filter terms used across all datasets in a Beacon and the latter providing information on filter terms used within specific datasets.

The response received from these endpoints - as per issue #44 - includes the meta wrapper.

A filter term includes the type property that is the full name of an ontology, "numeric", "alphanumeric" or "custom".

The ontologyResource object has been added alongside the filterTerms and is based on the Phenopackets resource object. The ontologyResource is referenced within each filterTerm via the filterTerm.type property which has an exact match with an ontologyResource.name. This avoids enforcing the use of namespace prefixes to identify ontologies when the prefix may be absent and/or varies between sources (e.g. MIM/OMIM).

Filters within requests are formed from a list of filter terms (the logical AND is implied between filters), the format of the filter term depends upon the type of filter being queried. Example filter request objects:

  {
    "id": "HP:0002664",
    "includeDescendantTerms": true,
    "similarity": "exact"
  },
  {
    "id": "age",
    "operator": ">",
    "value": "P70Y"
  },
  {
    "id": "demographic.ethnicity:asian"
  }

[mbaudis]

@tb143 , all: Looks good, with 2 comments:

• it is common to have ontologyClass as objects with id (required) and label (optional); we had settled this through the Metadata Task Team in 2016 :-) (see also Phenopackets)
• this & your use of the "Phenopackets resource object" are perfect examples why we need a JSON Schema version of Phenopackets and other standards. We have the Phenopackets v1 in SchemaBlocks, but this has to become sustainable.

[jrambla]

IMU, this is solved. Reopen otherwise.