Harmonize the use of `biolink:supporting_text`

[isbluis]

The biolink:supporting_text attribute is used to provide contextual evidence of text-mined associations between a subject and a publication. According to the Biolink Model documentation, it has a value of type String, which can be multivalued (i.e. a List).

Various KPs and ARAs, however, do not seem to follow this specification. This may cause an issue for tools that parse these results downstream, with a likely outcome of not displaying to the user the supporting text from the publication presented as evidence for a given edge / relationship.
Anecdotal evidence suggests that this is already happening in production.

Should TRAPI explicitly specify and enforce the allowed value types of this attribute?

Summary (examples follow):

• RTX-KG2 encodes all as a dict with the key being the PMID of the source publication
• ARAX encodes it as a list, but it always(?) seems to have a length of one, and that single array element is the kg2-style dict
• BTE's is a simple string array with no context (though it seems to correspond 1:1 with the items in the biolink:publications array).
• Text Mining Provider embeds this in sub-attributes of biolink:has_supporting_study_result

Examples

RTX-KG2: First edge in first Analysis of this response:

ARAX: In result 1 -> Support Graph -> edge in this response:

BTE: under the "preventative_for_condition" edge in first result here:

Text Mining: In result 8, click on the one edge, then its support graph, and look at the fourth edge from the top -- "biolink:treats_or_applied_or_studied_to_treat" -- it has a bunch of sub-attributes:

[edeutsch]

@gprice1129 what does the UI do with these very different formats?

[gprice1129]

@edeutsch currently we attempt to distinguish between the different uses and process them accordingly

[edeutsch]

@gprice1129 does this like an okay state as is, or does it seem like consolidating on one format would be better? and is there a preference?

[colleenXu]

My team's understanding was that we should do the "Text Mining" approach, since the UI handles this right now.

We tried in the previous phase, but our attempt broke how we handled other KPs (with their own attribute-modeling quirks) so we reverted. And we also notice some limitations/difficult-to-implement design decisions in the "Text Mining"/UI approach like:

• 1 attribute per publication, all with the same top-level key (has_supporting_study_result)
• the top-level value isn't really meaningful, it's practically just a placeholder
• only 50 publications represented per edge
• only 1 sentence per publication
• yet data structure is verbose, so including publication info seems to balloon size of response a lot and it seems hard to increase the number of publications represented.

[colleenXu]

[EDITED: 2025-11-04]

But stepping back...I think this is mostly a DINGO/MUTT discussion topic. In my opinion...

First, we need to decide/get clarity on the ONE WAY Translator should represent this kind of edge data using biolink-model properties.

Then, we can lay out how this is supposed to look in KGX output. And the ingesters can create "refactored" KG output that is all standardized to this format. (To fix the confusion of all KPs/KGs formatting this data differently.)

And then lay out how this is supposed to look in TRAPI (how many edge attributes, attribute format/nesting...). The DAWG/Retriever folks would want to know this info so they can take their internal Tier/Dogpark data and transform into TRAPI responses (related to TOM tool?).

Then the output given to the UI can be standardized and in 1 format.

[gprice1129]

@edeutsch from the client standpoint a single format for how to present supporting text information would be preferable. I agree with @colleenXu that the biolink:has_supporting_study_result attribute is extremely verbose. At a higher level we ultimately we think this attribute's aim is to get the user as close as possible to understanding why and where this claim is being made in the source text.