Has biothings explorer ingested enough of KEGG? If not, then should we create a KEGG beacon?

@cmungall I think you said you liked this idea at the Hackathon? Should we go ahead with it?

@RichardBruskiewich @cmungall Now that the source filters are not required, should the source and target filters be functionally equivalent? Or, should the target filters only apply if the source filters apply?

Alternatively we could get rid of them entirely, and replace them with subject and object filters. That makes more sense to me anyway, since the predicates are almost always directed. With the kmap one could easily figure out whether they should be filtering on the subject or object, anyway. The source and target filters are much more difficult to implement than subject and object filters would be.

I just came across this endpoint: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=22733540&retmode=json from https://www.ncbi.nlm.nih.gov/pmc/tools/get-metadata/, which gives information such as author names, publication title, journal name, volume, issue, pages, first (lead) author, last (senior) author, reference count, language, and exact matches (I see they have: pii, doi, pmc, mid, rid, eid, pmcid).

Currently in the beacons we're only displaying date, evidence type, id, name, and uri. It seems like we're missing out on information that could be relevant to weighting edges.

@cmungall @RichardBruskiewich should we expand the evidence properties in the beacons to include all of this?

Following on from discussion with @micheldumontier @newgene @jmcmurry @balhoff this a.m

We can implement a beacon directly over linked data. If a URL resolves to triples, we can just follow these outwards, gradually building out the graph.

Not clear what strategy should be for CURIEs, just use URLs directly?

cc @balhoff @micheldumontier

Contact team IR fordetails

When searching for concepts, exact matches are mixed in with matches that contain the search term, including matches with the search term in the middle of a word. This can cause the search results to have low relevance. One example is that when searching for "liver," the 1st result is "Drug Delivery Systems," the 4th result is "Liver dysfunction," and "Liver" doesn't appear until the 3rd page.

We need to be more clear about what beacons are supposed to do when they execute searches. The order could work like this:

1. Results whose names exactly match the search phrase come first, e.g. if you type in "diabetes mellitus" and there is a concept with the name "diabetes mellitus", then that concept would come before "diabetes" or "gestational diabetes mellitus".
2. Results whose names exactly match a term in the search phrase come second. So if you search "liver" then "liver disfunction" should come before "Drug Delivery Systems"
3. Then, results whose description or definition exactly match a term in the search phrase come third.
4. Then, finally, any other hit can follow. It's acceptable that "Drug Delivery Systems" would appear for "liver", as long as it comes after anything relevant to the liver.

Also all keyword matches should be caseless. "diabetes mellitus" should match "Diabetes Mellitus".

It would actually be helpful in beacon client design to have access to the full list of predicates being used in statements from a beacon, plus a precise definition on their interpretation including directionality of application (e.g. subject => predicate => object direction). At some point, one may even suggest that a global ontology of predicates be established with a central catalog of predicates established to encourage reuse (and perhaps, global CURIEs)

This proposed API call obviously should also be proxied and pooled through to the beacon-aggregator

@stuppie notes that our original list lacked categories such as 'sequence variant', which will be crucial

@andrewsu note that we may need some unknown, or root level category such as 'Thing'

Can knowledge beacon API be updated so that predicates can have tag-value attributes (similar to what concepts have)

cc @vdancik @mwawer

@cmungall @RichardBruskiewich @vdancik Must we support random access pagination (getting a page of a given offset and size)? Would it be troubling to support only iteration (getting the next page of a given size)?

There may not be a bijective mapping from the knowledge source's records to the statements we want to extract. Sometimes I might infer a single statements from multiple records, or multiple statements from a single record. And sometimes I'm not able to apply filters when getting records from the knowledge source, and I must throw away records that don't match the filters. This is easy if we don't need to support random access, and pretty challenging otherwise. With NDEx we've been caching all results and then returning pages from the cache, but that seems like a pretty impractical solution.

See notes from call: https://docs.google.com/document/d/19qzMnV0_3VqiMFWGhGWYNm94xiP8hsFueKRVK17l6Og/edit#

... since the s and t concepts are arrays?

We would like a client to be able to ask a beacon what info it contains and how much

@micheldummontier will work on a PR to do this. We won't necessarily merge this, as it seems that the swagger is generated from the code.

By default, Spring's @RequestMapping truncates everything after the last . in a @PathVariable. For example, "complex.filename.html" is passed in as "complex.filename". This is a problem for API calls of the form /path/{value}.

For example, for the request /exactmatches/HGNC.SYMBOL%3ADMBT1, Spring passes "HGNC" in into the conceptId variable, as if you had requested /exactmatches/HGNC.

This issue affects the beacon aggregator as well as the translator knowledge beacon. I haven't checked the reference beacon.

Should perhaps the /concept/{conceptId} API endpoint be modified to take the clique list of identifiers rather than just the single identifier(?). See related issue NCATS-Tangerine/beacon-aggregator#24.

The main purpose of this repo is to provide the API standard for implementors, here: https://github.com/NCATS-Tangerine/translator-knowledge-beacon/tree/develop/api

the README should mention this first - and then the swagger codegen info

Separate reference (e.g. pmid), evidence type (e.g. ECO), source (i.e. database from which it was extracted)

Steve showed an example of using the prov model: https://github.com/NCATS-Tangerine/cq-notebooks/tree/master/GreenTeamQ1_Asthma_Outcomes_PM2.5_Ozone_Exposures

This endpoint would be like the kmap for exact matches. This is an example of what kind of data it would return:

[
   {
      "clique_mappings":[
         {
            "prefix":"OMIM",
            "uri":"http://purl.obolibrary.org/obo/OMIM_"
         },
         {
            "prefix":"Orphanet",
            "uri":"http://www.orpha.net/ORDO/Orphanet_"
         },
         {
            "prefix":"UniProtKB",
            "uri":"http://identifiers.org/uniprot/"
         }
      ],
      "frequency":905,
      "local_prefix":"NCBIGene",
      "uri":"http://www.ncbi.nlm.nih.gov/gene/"
   },
   {
      "clique_mappings":[
         {
            "prefix":"WBPhenotype",
            "uri":"http://purl.obolibrary.org/obo/WBPhenotype_"
         },
         {
            "prefix":"UPHENO",
            "uri":"http://purl.obolibrary.org/obo/UPHENO_"
         }
      ],
      "frequency":2286,
      "local_prefix":"HP",
      "uri":"http://purl.obolibrary.org/obo/HP_"
   }
]

This would essentially say that the beacon has concepts identified by NCBIGene and HP curies, and that it can produce exact matches between OMIM, Orphanet, UniProtKB, and NCBIGene, and between HP, UPHENO, and WBPhenotype.

This will be useful for clients (e.g., the beacon aggregator) to be able to know whether or not they should query a beacon when trying to build up concept cliques. It would also document the case of the curie prefixes (e.g., "NCBIGene" vs "NCBIGENE" vs. "ncbigene") that the beacon uses.

I recommend this is done via the sparql endpoint. I can provide the sparql required

Should be possible to compare the results of a query on an object (eg gene disease) across beacons

Not all data sources wrapped with the Beacon API can implement all endpoints. Should we have a more formal mechanism. in the API to inform clients of what is implemented and what is not?

On this gene:

There are no links to diseases

these are available through the monarch instance of biolink:

https://api.monarchinitiative.org/api/bioentity/gene/OMIM%3A126650/diseases/?fetch_objects=true&rows=100

The only query results seem to be wikidata and semmeddb, even though I have others checked:

The logs don't help much - I click to see these and it takes me to https://kba.ncats.io/errorlog?sessionId=s3Wg7ENqMudJy75fyJbA which is a json file with [] in it

With the introduction of the shared biolink semantic model, it is still useful to expose the "local_id" which is being mapped onto the Biolink Model. We should modify the JSON output accordingly, with a "local_id" field (and possibly, a xrefs field?)

set a predicate parameter to reflect something like 'owl:sameAs' to retrieve mappings.

this would reduce the number of services in the API and make it clear that we would like to see evidence and provenance for these relationships - just like any other relationship returned by a service.

A few possible loose ends in the 1.1.0 release:

• /kmap should return the 'negated' parameter for the predicate value of a mapping
• there may be utility in extending the metadata endpoints to include the following:

1. A Beacon "/light" endpoint which simply serves as a low overhead 'ping' if a beacon is online
2. A Beacon '/description" endpoint which returns a significant amount of the descriptive documentation which is currently annotated in the Beacon list file

Beacon API proposals:

1. Change the evidence date to a json object {"year" : 2015, "month" : 4, "day" : 23} rather than a string. If we do this then there is no possibility of different beacons formatting dates differently, and will allow applications to get this information without having to parse date strings.
2. Add some sort of qualification flag/status for statements that have been inferred through either deduction or heuristic. What is the best way to display this?
3. Optional sub-graph ID? Some knowledge sources (like NDEx) are really a collection of independent knowledge graphs. In that case we might want to be able to choose which of those sub-graphs to query.
4. Replace the statement source and target filters with subject and object filters. See #61, #60
5. Set appropriate minimum and default values for size and offset. It makes the logic easier if we don't have to handle null values, and it prevents an accidental dump of the whole knowledge source. We may wish to set a max size as well, something like 10,000?
6. Metadata endpoints should report the total number of nodes (concepts) and edges (statements)
7. Concept and statement details endpoints should take a list of identifiers and give you a list of detail entities.
8. Bring back synonyms on concepts endpoint. This way we can display gene symbols as well as protein names.
9. Replace/complement random access pagination with a next page token. NDEx, for example, only supports pagination over networks and not over the nodes and edges in those networks. The NDEx beacon's next page token could represent: {network=5, offset=62, size=800}. Thus allowing each beacon to implement pagination with as many parameters as it needs. #59. Along with the next page token we can return, whenever possible, the total number of records for that query.
10. Remove fields from metadata endpoints: /categories remove uri, local_id, local_uri, add local_category. /predicates remove id, uri, local_id, local_uri, local_relation.
11. Remove separate details endpoints. Instead have the response fields be configurable. User can pass in a list of fields, and those fields will show up in the response.
12. Add an endpoint that returns metadata about the beacon (rather than the knowledge graph), like its name, its github page, a wiki or jupyter notebook explaining how to use it (maybe all beacons can share one), who to contact about it, and a link to the knowledge source it wraps.

Aggregator API proposals:

1. Add publication metadata to evidence, including the publications title, abstract, authors, journal, volume, issue, page numbers, page count, reference count, and language. See #56.
2. Use the publication metadata to implement a statement score, and display that score in main statements endpoint. An initial scoring mechanism could be something like this:

score = 0
for line in abstract.split('.'):
    score += line.count(subject_name) * line.count(predicate_name) * line.count(object_name)
score = sigmoid(score)

See September 26, 2018 comment inside issue #40 for details.

The idea is that responses from a server should include URLs that are themselves API calls on the same server

https://en.wikipedia.org/wiki/HATEOAS

For examples, see the PHAROS API

Time to review the good, the bad and the ugly of the overall objectives, big picture design and implementation priorities of the Knowledge Beacon API. After 9 months of working with the concept and the specific initial implementation, what would we do differently now? What is missing (e.g. Provenance)? What is less useful or awkward to use? Is there a better way to specify it? Is the data representation optimal (e.g. REST/JSON) or would a RDF/LOD standard work better? What specific standards should be enforced (e.g. data type semantics? relation predicate semantics?) Are there any practical operational issues (e.g. standards for dealing with problematic queries? Exception/error reporting)?

API changes related to NCATS-Tangerine/beacon-aggregator#91 (comment)

This is a proxy "mega" issue to cover a general review, rehabilitation and documentation of the Knowledge Beacon technology stack.

See https://github.com/NCATS-Tangerine/translator-knowledge-beacon/blob/develop/api/knowledge-beacon-list.yaml for master list

• SemMedDB - @RichardBruskiewich
• Wikidata (aka garbanzo) - @stuppie
• String-db.org wrapper - @lhannest <-- first add link to github repo in beacon-list.yaml
• Red - @victorganic
• Monarch Biolink - @lhannest
• Monarch Ontologies - @kshefchek
• Bio2RDF - @micheldumontier
• Pharos - @amalic
• ISB Translator API - Blue team
• nDex Bio - @meera-gd

The taxon (species) that a particular concept (especially, gene concepts) pertain to is an important discriminator of concepts but is not explicitly returned by the Knowledge Beacon API in any endpoint, except perhaps as ancillary data in the /concepts/ call which returns concept details. Also, the /exactmatches API calls do not also well discriminate between equivalent concepts that are taxonomically distinct (e.g. orthologous gene loci from different species). Attempting to capture and return the taxonomic identity (e.g. NCBI taxonomy id?) for concepts in the various endpoints, would help fix this issue.

Consider whether to fold into main API

Should probably have some parameter in the API response to indicate which service provided which piece of data. (e.g. service: http://stars.renci.org somewhere in the response).

This becomes important for clients when aggregating and displaying data coming in from many places.

Maybe just part of the evidence API ?

Some kbeacons may like to support the ability to access a particular version of the data. Obviously not all beacons can support this.

date should be returned in payloads, and also as an optional parameter (http header) in queries?

Team discussions with @vdancik, @cmungall and this writer suggest that a modest iteration on the Knowledge Beacon API is desirable. Here are the tables of proposed change (alternatives):

To some extent, the /concepts keyword search is Google - like in that matches to any of the keywords are returned. Generally, it is suggested that a ranking of "high quality" (more keywords matched) results returned first versus "lower quality" result returned further down the list, is assumed (need to check if this expectation is well documented in the API).

However, it may be the case that users are only interested in "exact matches" to all keywords. Adding an "exactMatch" or "matchAll" flag to the input parameters as an expectation, could be helpful to make the keyword search more precise for some use cases.

Q: Do we need both: "exactMatch" might mean "exactly verbatim as written (keywords in order and including whitespace)" versus "matchAll" which might imply that the concept name must include (i.e. "match") all the keywords specified?

Need to make this easier than it currently is.
Need an easy for people to test that their Beacons are conforming to a specification.

• Create a validator script

We are exploring architectures such as linked data fragments to be able to support queries involving joins across k-beacons. We realize that this may be massively inefficient at first, but that is fine for demoing purposes

@balhoff has implemented a demo of LDFs wrapping k-beacons: https://github.com/balhoff/beacon-tpf

with @stevencox @balhoff @jmcmurry

For smartapi and beacons we will define a way a knowledge source can advertise what types and identifiers are related by what relations/predicates.

This would be a list such as the following

-
  subject:
    semantic_type: gene
    prefixes:
       - NCBIGene
       - ENSEMBL
       - HGNC
       - MGI
  predicate:
    id: RO:nnn
    label: has phenotype
  object:
    semantic_type: phenotype
    prefixes:
       - MP
       - HP
  count: 500 # optional
  description: >
     blah blah
-
  ...      

We're currently using the multi format for arrays, which looks like:
/api/statements?c=X&c=Y&c=Z

But this raises a problem. Most people want to use Python Flask to write their API's, but the Swagger Codegen application generates API's that use Connexion, which do not support the multi collection format.

Connexion only supports the csv and pipes collection format, which looks like:
/api/statements?c=X,Y,Z
/api/statements?c=X|Y|Z

I have been trying to develop Connexion to support the multi collection format, and if I accomplish this then the issue is resolved. But otherwise, we might want to use a different collection format so that developers can use Swagger to generate Python Flask project stubs.