KisaoAlgorithmSubstitution schema question

[jmdetloff]

I have a quick question about the schema for KisaoAlgorithmSubstitution

(The api is 500'ing at the moment btw, but I see there's already an issue for that)

I'm looking at https://github.com/biosimulations/biosimulations/blob/dev/apps/combine-api/src/spec/spec.yml#L2081 and could use some clarification on how I should understand the property 'maxPolicy'.

From the description here it seems to me that this property should be named 'minPolicy'? In order for these two algorithms to be swapped, the policy must be at least this high/lenient, so this is the minimum policy for which these two algorithms can be swapped? Policies lower than this value would forbid the swap, and policies greater than or equal to it would allow the swap? I just want to confirm my understanding here is correct. Should this property name be changed?

Also, I believe the definition at 2073 is meant for the maxPolicy property, not for the KisaoAlgorithmSubstitution class. And there is a typo at 2022 which/switch. Happy to pr a fix for these once I wrap up my current change if there's a definition for KisaoAlgorithmSubstitution I can paste in.

Another point of clarification while I'm thinking of it - the KisaoAlgorithmSubstitutions, are these algorithm substitutions that are enumerated within KISAO, or are they substitutions of algorithms enumerated within KISAO. (I poked around in the KISAO browser on BioPortal and didn't see anything that looked like enumerations of similar algorithms.) If the former, where did the substitutions originate from and are they documented somewhere other than the api? Did your team compile these?

[jonrkarr]

(The api is 500'ing at the moment btw, but I see there's already an issue for that)

The API is running. This issue only affects the Swagger UI app which displays the documentation.

In order for these two algorithms to be swapped, the policy must be at least this high/lenient, so this is the minimum policy for which these two algorithms can be swapped?

Yes

From the description here it seems to me that this property should be named 'minPolicy'?

I renamed this to minPolicy in some places where this might be more intuitive.

I think min or max depends on how the information is being used. I called it maxPolicy because this controls the maximum degree to which a simulation could be run with an alternate algorithm without raising an error. From the perspective of a user who wants to run a simulation, this seemed to be a reasonable way to think of this. Alternatively, you can think of this as the minimum policy at which a pair of algorithms can be substituted. I think this is a good way to developers to think of the information which we use to make decisions for the user.

Also, I believe the definition at 2073 is meant for the maxPolicy property, not for the KisaoAlgorithmSubstitution class.

Thanks! I edited this.

FYI, we're using Apicurio studio to edit the specifications for the API. Its a convenient graphical editor for OpenAPI specifications. We then export the specifications (including dereferencing it) and save it into the BioSimulations repository.

And there is a typo at 2022 which/switch.

Thanks! I edited this.

are they substitutions of algorithms enumerated within KISAO

Good question! The degree of substitutability traces back to this code: https://github.com/SED-ML/KiSAO/blob/1a0d2a6d55d46bad475431569e8e55d2a7394cb3/libkisao/python/kisao/utils.py#L285

Conceptually, this can be thought of as a list of the pair-wise similarity of algorithms or an algorithm by algorithm matrix of their similarity. I think the matrix way of thinking about it is helpful because it helps build intuition about the global structure of this similarity. Because there are groups of similar algorithms, the matrix is substantially banded (i.e., most pairs of algorithms of very dissimilar; if two algorithms are similar and one is similar to a third, the second is also typically similar to the third).

The code above uses three types of information

• (a) Parent/child information and (b) other types of relationships encoded into the ontology
• (c) Degree of similarity encoded into the code

Ideally, we'd solely rely on information in the ontology, but we haven't gotten to encoding this information better. Encoding this information better would enable us to calculate these pairwise similarity with a SPARQL query (similar to a database query over a set of RDF triples).

[jmdetloff]

Interesting, thanks for expanding on this!