Function Variants in the Constraint Model

[DanielPuthawala]

This is a thread to host discussion pertaining to the the development of the FunctionConstraint cover function variants in the constraint-based framework of Cat-VRS.

Below is the current demo version of a function variant in Cat-VRS, from the main constraint model discussion thread, and with some extraneous material pruned. (there was some spillover from the CatCNV mockup).

[brendanreardon]

I love it! A couple of comments and thoughts are:

Can you expand upon how GeneContextConstraint differs from using definingContext and it being set to Gene? I was typing out a bit wondering about alternative constraints such as such as "ArmContextConstraint", "ChromosomeContextConstraint", etc., and then realized that these all may be captured under the defining context model.

What do folks think about functional constraints maybe requiring an OR logic, as constraints using a list structure only really enables AND logic? In this example of general "BRCA1 loss-of-function", I could imagine that matching to either SO:0001561 - partial loss of function or SO:0002054 - loss of function. I guess the latter covers this ambiguity by having the definition containing "diminished or abolished function".

[DanielPuthawala]

Can you expand upon how GeneContextConstraint differs from using definingContext and it being set to Gene?

IIRC the reason we had a difference was because using something like a vrs:location in theDefiningContextConstraint entails providing a genomic coordinate range, which would thus require people to specify exact what nucleotide range they mean by BRAF, when we don't necessarilly want them to b/c a precise definition of a gene has never been agreed upon? (and that would invite overprecision)? I think this is an excellent question to bring up tomorrow, though, and I'll ask if @ahwagner can elaborate.

As for your second question (which is also good), I do have thoughts (which probably surprises noone). Here we're modelling properties that lie on scales. Specifically, a bottom closed scale (if you want to read more about semantic scales and a typology thereof, I reccomend this seminal paper in lexical semantics Kennedy & McNally 2005 which is pretty approachable if you ignore all of the math and just focus on the examples they give). So this is similar in intuition to an adjectives like "straight", "quiet", or "unknown". Here's what I mean with"straight", and then how it applies to "loss", and then, I promise, a relevant point about the logic here.

A pipe can be completely, 100% straight. There is a maximum degree of straightness where the scale ends. Then it can become a little, a lot, or an arbitrary amount of no-straight, but there's no maximal degree of not-straightness.

• This pipe is fully straight.
• This pipe is mostly straight.
• This pipe is a little straight.
• This pipe is not really straight at all.

But you can't really felicitously say

• This pipe is fully bent.
  (that's means that while there is a lower bound on the scale to straightness, there is no upper bound on it.)

(The same is true of the natural numbers, you have a minimum, 0, but no maximum value)

The same thing is true of function gain/loss

• Complete loss-of-function
• Partial loss-of-function
• Gain-of-function
• high level Gain-of-function
• super high level gain-of-function
• super dee duper high level gain-of function...

Why this is relevant is that we exploit these scales to imply things. If you ask how a student did on a test and they say, "I passed", you're likely to intepret that as meaning that they did not fail, but also did not do well, because even though an A is a passing grade, fi they HAD gotten an A they could have just as easily said "I aced it" and been more specific, so we take the fact that they didn't say "I aced it" as evidence that they did not in fact do well.

Ok, so translating into genomics and CatVars, people may say "Loss" and mean it as anything lower than normal function. but other people could say "Partial loss-of-function" if it was not complete loss, and so along the same lines of the logic above, interpret "loss of function" to mean a complete loss of function. So in short, there are reasons to suggest that "Loss of function" itself is ambiguous between being a partial-to-full loss-of-function or strictly a full loss-of-function.

And I am not 100% sure what we want to do about that.

[brendanreardon]

IIRC the reason we had a difference was because using something like a vrs:location in theDefiningContextConstraint entails providing a genomic coordinate range, which would thus require people to specify exact what nucleotide range they mean by BRAF, when we don't necessarilly want them to b/c a precise definition of a gene has never been agreed upon? (and that would invite overprecision)? I think this is an excellent question to bring up tomorrow, though, and I'll ask if @ahwagner can elaborate.

That makes sense! I think that this relates to the discussion on this morning's call too, right? Specifically about dividing into splitting up Variation and Location from the definingContext constraint.

I LOVE the example that you used relating pipe straightness to gain of function. When we get into this in a future call, I think walking people through this illustrative example would be a very helpful conversational aid.

[DanielPuthawala]

Yes, the suggestion to break up the DefiningContectConstraint, while not exactly due to the same concern, would give me an opportunity to take another crack and solving this issue, ie having a LocationConstraint that subsumes the degrees of specificity available to either the current DefiningContextConstraint and/or GeneContextConstraint. So that may well be a blessing in disguise.

[brendanreardon]

I tried to capture the current lucidchart for function variants in this branch: 16-update-function-variants. I either made modification to or added new files to schema/cat-vrs/:

• Added FunctionVariant to recipe-sources.yaml
• Added and populated json/FunctionConstraint, json/GeneContextConstraint, def/FunctionConstraint.rst, and def/GeneContextConstraint.rst
• I also pre-committed an empty functionVariant.yaml in examples/ that I'll populate once the schemas are okay'd.

For FunctionConstraint

• I used the CopyChangeConstraint as a model. For the sequence ontology choices for the functionConsequence property, I was torn between listing them under either enum or oneOf and ultimately settled on enum. The examples of oneOf being used within the property throughout the repository seem to all be for a list of dictionaries, whereas enum seems to be used for a list of strings.

For GeneContextConstraint

• I used DefinitionLocationConstraint as a model.
• For the relations property, there may be some inconsistency in genome_liftrover and sequence_liftover throughout some constraint definitions, I think. I left the description for genome_liftover to be the same as sequence_liftover from the definingLocationConstraint, as it broadly seems to be equally as applicable. I know that the definingLocationConstraint is actively being reworked per the ASHG un-conferencing w.r.t. the copy number constraints, which is probably contributing.
• With that said, I feel kind of underwhelmed by GeneContextConstraint at the moment. While definitionLocationConstraint requires a vrs allele, it would be nice to at least require an hgnc id and transcript in absence of being to vrs-ify a genes in a location-independent way. Feel free to punt all discussion about this to the Context Constraints discussion.

To note, there was a lot of dialogue at the 2024-08-27 meeting about potentially adding "function target" as a property. Ultimately, this was decided to be omitted from the initial draft, with the possibility of revisiting this property if needed. This was because there is a desire to keep the constraints to be focused on variant-specific details within the scope of this working group.

[brendanreardon]

Adding my comments on the current state of the branch 16-update-function-variants here.

schema/cat-vrs/cat-vrs-source.yaml, added FunctionConstraint in commit 4a55fd9:

• This seems to be a mix of the FunctionVariant recipe that I added to recipes-source.yaml and the schema/cat-vrs/json/FunctionConstraint.
• This lists maturity as "trial use" maturity instead of "draft use". Shouldn't it be draft use, since it is not included in the current trial ballot?
• The "type" property is written as "extends: type" whereas in the json I had it as "type": "string". "extends: type" is a bit confusing to me. Can you help me understand what I am missing?
• Under properties > required, this does not include "type". It seems like the recipe-sources.yaml don't have "type" required under properties but the json schemas do. Can you help me understand what I am missing here? (edit: it looks like this was removed from the json files in Daniel's commits)

schema/cat-vrs/cat-vrs-source.yaml, added GeneContextConstraint in commit 4a55fd9:

• This likewise lists maturity as "trial use" maturity instead of "draft use". Shouldn't it be draft use, since it is not included in the current trial ballot?
• The description is listed as, "The functional unit of inheritance that members of this categorical variant are associated with" and I had "A free-text description of the gene context that members of this categorical variant satisfies" based on the LucidChart. The former is definitely more general, but I worry that it is maybe too abstract for users. What do you think?
• I believe that there was a comment in one of the discussion threads about what should or should not be listed under relations' enum. I had "genome liftover" and "transcript progression" based on the lucidchart and, here, you have: "translates_from", "translates_from_reading_frame", "liftover_to", "transcribes_to", "translates_to", "translates_through". I believe that these are from the Canonical Allele relations. Are you, Alex, and Larry pulling these recommended enums from somewhere? Likewise, the relations description is listed as TBD here. Maybe we'll leave this empty until we lock down what the enums should be for this constraint.
• Similar to the FunctionConstraint, under properties > required, this does not include "type".

Daniel's third commit, d248627 is the biggest.

• Daniel Slack'd me about removing some of the .rst files because they are generated from the makefile based on the cat-vrs-source.yaml.
• The maturity level was moved to draft here for FunctionVariant.rst, which makes me think that both should be draft within schema/cat-vrs/cat-vrs-source.yaml.
• To clarify, schema/cat-vrs/def/FunctionVariant.rst and schema/cat-vrs/json/FunctionVariant were generated from cat-vrs-source.yaml, right?
• Is it okay to not commit a version of GeneContextConstraint at the moment, even though that it is required for schema/cat-vrs/def/FunctionVariant? At the moment the GeneContextConstraint def and json are removed from this branch.

[brendanreardon]

In summary, this looks good at the moment! Except, I think...

• GeneContextConstraint, FunctionConstraint, and CopyChangeConstraint within schema/cat-vrs/cat-vrs-source.yaml should have maturity: draft
• Review and agree upon GeneContextConstraint description as well as relation enum and description, if within scope of this branch.

And questions that I have are:

• Can you catch me up on what properties > type > extends> type means?
• Why didn't the make function generate a def and json for GeneContextConstraint, despite being present in the cat-vrs-source.yaml? Maybe it actually just was not committed?
• For organization within cat-vrs-source.yaml and recipes-source.yaml is there any structure that you folks have been following for definition ordering?

[DanielPuthawala]

• This lists maturity as "trial use" maturity instead of "draft use". Shouldn't it be draft use, since it is not included in the current trial ballot?

Oops! Yup, I'll fix that.
Aaaand double-oops, @larrybabb and @ahwagner we forgot to include Constraint in the TU ballot release. we'll need to do that for the next one, since all of the existing TU constraints are based on that abstract class.

• The "type" property is written as "extends: type" whereas in the json I had it as "type": "string". "extends: type" is a bit confusing to me. Can you help me understand what I am missing?

I'm not 100% certain what this bit does, either, but I'll take a stab at explaining how I understand it, and @ahwagner can you correct me/elaborate where necessary?

The Constraint abstract class has a heritable type property, which must be a string value. Subsequent constraints that inherit from Constraint have to specify a value there to be a valid schema. As for why Constraint requires its inheritants to specify a type, I think this is mostly required so as to have the various child constraints be differentiable, because each schema has a name, but this way there's a part of the schema that specifies which schema it belongs to, rather than you having to determine which schema it belongs to by trying to validate it against all your schemas until one works. This functions kind of like writing a label on your keys as to which door it opens? Like yes, in principle, there's only one door it opens, and you could figure that out by trial-an-error, but it's often faster and easier to also write the name of the room it opens on the key so you just know where to use it without the guesswork.

• Under properties > required, this does not include "type". It seems like the recipe-sources.yaml don't have "type" required under properties but the json schemas do. Can you help me understand what I am missing here? (edit: it looks like this was removed from the json files in Daniel's commits)

AFAIK this is simply because we don't have an analogous abstract Recipe class that the various recipes inherit from like we did with the constraints. I don't remember if we discussed this idiosyncrasy or not, or what the conclusion of that discussion was.

schema/cat-vrs/cat-vrs-source.yaml, added GeneContextConstraint in commit 4a55fd9:

• This likewise lists maturity as "trial use" maturity instead of "draft use". Shouldn't it be draft use, since it is not included in the current trial ballot?

Yup.

• The description is listed as, "The functional unit of inheritance that members of this categorical variant are associated with" and I had "A free-text description of the gene context that members of this categorical variant satisfies" based on the LucidChart. The former is definitely more general, but I worry that it is maybe too abstract for users. What do you think?

I'll defer to you and the others here. I modeled it on the language we use in other constraints, but am not attached to either description. This seems like a dicily nuanced bit, because we don't want to define what a gene is, just what the things are that we are using in our constraint.

• I believe that there was a comment in one of the discussion threads about what should or should not be listed under relations' enum. I had "genome liftover" and "transcript progression" based on the lucidchart and, here, you have: "translates_from", "translates_from_reading_frame", "liftover_to", "transcribes_to", "translates_to", "translates_through". I believe that these are from the Canonical Allele relations. Are you, Alex, and Larry pulling these recommended enums from somewhere? Likewise, the relations description is listed as TBD here. Maybe we'll leave this empty until we lock down what the enums should be for this constraint.

@larrybabb and @ahwagner did some work on this recently, and I admit I'm still not sure where this issue landed, and would appreciate some clarity. We could put this on the agenda for a future Cat-VRS call.

• Similar to the FunctionConstraint, under properties > required, this does not include "type".

None of the constraints require type. Constraint requires that each child object specify a type, but I'm not sure I understand this question?

• The maturity level was moved to draft here for FunctionVariant.rst, which makes me think that both should be draft within schema/cat-vrs/cat-vrs-source.yaml.

You're correct. I goofed.

• To clarify, schema/cat-vrs/def/FunctionVariant.rst and schema/cat-vrs/json/FunctionVariant were generated from cat-vrs-source.yaml, right?

Yes!

• Is it okay to not commit a version of GeneContextConstraint at the moment, even though that it is required for schema/cat-vrs/def/FunctionVariant? At the moment the GeneContextConstraint def and json are removed from this branch.

They were?! Oh, ALL of the constraints were, only the recipes are showing up. That's odd. I'm gonna have to fix that...

[DanielPuthawala]

Your other observations and questions are addressed above.

• For organization within cat-vrs-source.yaml and recipes-source.yaml is there any structure that you folks have been following for definition ordering?

uh... not really? Other than having child classes below their parent. We probably should come up with something more consistant though.

[brendanreardon]

Thank you for such a thoughtful reply to all of those points! I pushed the trial use to draft modification for the relevant constraints within the branch.

Regarding the GeneConextConstraints descriptions, I totally agree that we don't get into the business of defining what a gene is. I may then defer Larry and Alex since they have undoubtedly run into this with vrs.

A side thought that I had last night - do you think that it makes sense to rename cat-vrs-source.yaml to be constraints-source.yaml? Since cat-vrs really is defined from both of them, right? Yes, cat-vrs-source.yaml defines the ingredients while recipes-source.yaml are the officially maintained ... recipes (I really like the rebrand to recipes).