A constraint-based model of CatVars

[DanielPuthawala]

The general approach to schemata in VRS, and by extension, the aspects that Cat-VRS inherited through VRSatile, has been to model different types of variants as discrete top-level data classes. Hence, having one data class for canonical variants, another for protein consequence variants, a third for CNVs, etc. There are, I think two potential issues with this approach in the categorical variation space: lots of significant (for clinical analysis and research) CatVars that fall into the cracks, and the need to compute entailments.

(The below rhetorical example is based on the CatCNV spec as per the 1.0.0.connect.2024-04.1 snapshot release)

CatVars in the cracks: If we consider just CNVs and sequence variants for a moment, we can, and have created two different classes for these. Sequence variants are in reference to a canonical allele, and some alternate sequence, while CNVs may also refer to some reference sequence and require some copy number or copy change value. Other than the fact that they both in reference to a stand genome build, there is little overlap in terms of the data types used in this two classes.

Now consider expression/function variants. These have a lot in common with sequence variants, and often contain information on some sort of sequence variation, such as a deletion, gene loss, stop gain, etc. But they also require a quantitative data field that has much in common with that from CNVs, but in this case typically something related to levels of gene product.

We could make a third, discrete, and independent data class of variants that contains features from both sequence variants and CNVs, but I don’t like this for a couple reasons. First, it’s not DRY. Second, if a CatVar entry is made, say, as a sequence variant, and then it turns out that there is a functional consequence of that sequence change, this would require re-configuring the CatVar as a function variant, not just adding the new functional information, which doesn’t seem efficient. And third, it doesn’t solve the problem. If we make that third class, there will still be variants falling into the cracks between them,

Entailments: Several of our use cases so far involve matching between categorical variants, and a subset of that involves determining if a given CatVar partially intersects or is a subset of another CatVar. If we have discrete, disparate variant classes, then we can explicitly code that CatVars in one class are subsets of those in another class, but making any other (eg orthogonal) comparisons become nontrivial given the apples-to-oranges nature of the data representations.

An alternative is to make a constraint-based model of categorical variation. In this model, instead of the top-level objects being classes of CatVars, the top level objects here are constraints on variation, with many of these constraints being optional. The top-level CatVar classes in the previous model here instead correspond to profiles which specify certain constraints that must be satisfying in order to belong in that class. Under this model, all CatVars are stored in a similar formal, just with varying degrees of optional constraints having non-null values.

This could solve the gaps problem, because even if a variant doesn’t fit into any given profile, it can still be represented as thoroughly or precisely as any other variant, as long as the spec has been built out enough to include the relevant constraint fields.

This also can solve the entailment/match issue, because computing the relationship between two given caters becomes an exercise of simply comparing their constraints on an apples-to-apples basis, since they all underlying have the same possible constraints fields.

I’ll sketch out a visual aid of these two approaches and add it below.

So, in summary, the proposal is to shift from modelling variant classes into modelling CatVar constraint classes, and that under the new model, conventional CatVar classes would correspond to profiles: lists of constraints with particular values indicative of CatVars belonging to that class.

[DanielPuthawala]

This sketch shows 2 CatVar classes under the current model.

[DanielPuthawala]

Under the constraint model, we have a set of constraints that are common to all CatVars. Now, CatCNV and Protein Sequence Variants are profiles which specify core constraints needed for a CatVar of that profile to be queried.

[DanielPuthawala]

A Function CatVar, showing constraints with or without non-null data values, and how it is a sequence variant by matching the required constraints of that profile, but we are also able to capture additional information that is more CNV-like, here being a relative change in sensitivity (here I'm deliberately construing "copyChange" as being generalizable to relative quantity changes.)

[brendanreardon]

Pairing this with Alex's comment below, are your labels for Profile 1 and 2 ...

1. Placeholders for specific CatVars (e.g., PIK3CA p.E545) or
2. Defining "sets" of CatVars that at least have non-null values for, at least, constraints connected by solid lines
   ?

[ahwagner]

So, as a general model, the constraints are applied following this general pattern?

[DanielPuthawala]

Yes, that's accurate!

[larrybabb]

This seems like a very reasonable approach to take. My biggest concern is whether this approach should be pursued in a 2.x release path because this change is a breaking change with vrsatile which our current 1.x model is based on. If we want this to be our 1.x direction I will need a very quick set of defined constraints for canonicalallele, categorical in, and variantdescriptor (text). Otherwise this will set the GKS pilot work back many months at a time where we have just finally gotten a 1.x pipeline set up after years of trying. That's a tough sell for me.

It comes down to how quickly we can draft a viable constraint schema and demonstrate how we discern one subtype of constraints from another. Will there be some standard and naming of constraint profiles? Can we put some sample data together from real world data really quickly. If not then let's pursue this as 2.x and stick with 1.x as is.

[DanielPuthawala]

Larry, Thanks for that feedback! I don't want to set you back, and I think that this hopefully will amount to a fairly small update on your end. (See below for some demos). As for the version numbering, I am less concerned about the 1.x vs 2.x distinction (because versioning is now both a function of breaking changes the maturty of the affected data classes) and more concerned with getting something to you that (a) won't be a pain to adopt if and when you're ready and able to, and (b) is compatible with the general model structure we anticipate needing so we hopefully don't have to overhaul it dramatically in the future.

[larrybabb]

I'd like to understand if we would create subclasses of the abstract constraint class for the various concrete concepts needed. Or if we would leave it to users to inspect a given constraint object to determine what type of catvar it actually is?

[DanielPuthawala]

That's the neat thing about the constraint model, you can do both/either. You can define custom profiles for whatever major CatVars you are interested in, but at the same time, this structure should allow us to parse out CatVar types on the fly, so you can determine exactly what type a given CatVar is (and determine if another is the same type/in the same class or not) on the fly.

[brendanreardon]

Thank you for laying this out so thoughtfully! I think the 4 figures currently presented in this discussion will be really wonderful visual aids in the next call. This is a very nice framework. I wonder if some of Larry's concerns come from the Connect release being labeled as 1.0.0, instead of leaving the major version to be 0.

[DanielPuthawala]

The connect snapshot release is just that, a snapshot so we have a point-in-time reference of where we were at connect. And AFAIK we need to start with at least a 1.x.x.

I'm assuming that we will version in lie with the proposed GKS maturity model (@ahwagner is that fit for public review/circulation yet?) but the basic gist is that all of the data classes are currently draft maturity status. updates to just draft-status classes entail a patch (1.0.1, 1.0.2, 1.0.3, etc). Moving classes up to trial-use maturity or making breaking changes to trial-use-status classes requires a minor release (1.1.x, 1.2.x, etc), and this is the point in which we will need PRC review and steerign approval to official launch or 'release' Cat-VRS as a GA4GH GKS product.

So Larry's concern seems more that he wants us to keep things unchanged for 1.1.0, and then update for 1.2.0, but I'm not sure that makes sense to submit what we started with for PRC review and approval, rather than what we're actually developing. But at the same time I don't want to cause him a huge headache. Hopefully the examples below show little would be required to be tweaked on Larry for CatVars of the existing canonicalAllele and categoricalCnv classes.

[DanielPuthawala]

@larrybabb Here's some examples of what updating a canonicalAllele CatVar and categoricalCnv CatVar would entail to make them compatible with a constraint model (borrowing the visual language of Alex's diagram). I am eager to hear your thoughts!

[ahwagner]

For the last example; shouldn't the members be VRS CopyNumberCount objects, not SequenceLocation?

[DanielPuthawala]

That would make sense, but I just pulled this from this pull from Clinvar, so that's on @larrybabb 's end?

[larrybabb]

Thanks @DanielPuthawala for putting together this side-by-side example.

While I agree with the comments above that this is a very flexible and extensible framework for defining all types and kinds of constraints to form various sets of variants into different Categorical forms, I'm not sure that is what we the cat-vrs specification is intended to do.

I'd like to the various techniques that a receiving system would have to engineer in order to discern what type of categorical variant they are receiving. If they are all explicitly typed as "CategoricalVariation" then I believe there may be less value in sharing it other than to generalize what is being received.

In VRS we wrestled with the idea of Typing the messages explicitly so that it would be possible for consuming systems to both validate the data type and have sufficient information to process it.

I suppose having a generalized schema is fine, but the specificity will come in terms of putting requirements on the constraints themselves. We are essentially pushing the issue of typing into the constraint nodes specification itself. I think this is a fine idea, but one that needs to be done a part of the definition of the various categorical variation that we want to define.

Optionality in a specification is great as long as it does not redefine a new concept. Getting the set of concepts that are comparable and contrastable such that they can be reasonably implemented by a system is the key. I understand that it is feasible to create a generalized model and then claim that by applying the constraints of two differently defined set of constraints you can still find the overlapping members, I'm not sure that is what we need to do.

What we need is the ability to figure out what the members are in a pragmatic way so that we can discern one instance of a categorical variant from another for the same set of constraints (aka. the categorical variant subtype). Then we can assign identifiers for these subtypes where the subtype itself acts as a kind of namespace. I believe this is a more sensible approach than thinking about all categorical variation as one thing.

[DanielPuthawala]

What we need is the ability to figure out what the members are in a pragmatic way

While I agree with you that CatVars are fundamentally sets of assayed variation, the problem is that in many cases, the possible cardinality of those sets is astronomically large. So determining if two CatVars are the same by lining up their members and seeing if they're the same simply isn't feasible. Suppose we have the CatVar "Insertions of <135 nucleotides in [POSITION]" that set has 4^134 possible members, roughly equivalent to the estimated number of atoms in the observable universe.

That's why Alex and I are defining the core of these CatVars not by their members, but the properties common to all their members. It is way faster and easier than checking if it matches one of the members of that set.

If you DO want to compare against members for really small sets or for sets with a couple really common or representative members, well that's what leaving the optional field in there is for!

[larrybabb]

One other observation. Maybe we need to simply define a "VariationConstraint" class that can be subclassed into the various forms, like CanonicalAllele (genomic defining context) or CanonicalLocation (genomic defining location) or ProteinExpression, ... etc..

Then a system can be engineered to reference the Constraint type to now when they are dealing with one type of categorical variation versus another?

Just a thought. I'm not sure this makes things more complex vs just putting subtypes on the CategoricalVariation itself (if we presume all different constraint types will share the same exact set of optional attributes (members, expressions, etc..).

[brendanreardon]

I have some time over the next week to work on some examples for the constraint model, as we discussed during last week's call. Can one of you point me to the current specifications for canonicalAllele and categoricalCNV? For sequence variants, the VRS documentation is robust plus there are examples in both the va-spec and gk-pilot repositories.

@DanielPuthawala if this would be easier as a call, we can definitely do that too 🙈 !

[DanielPuthawala]

I'm down to work with you, Brendan! We can coordinate a time offline here.

The most up-to-date ReadTheDocs is here, though this is running behind the current dev branch. If you want to see what is currently being worked on (not that I've made much progress in the npast week), you can find that in the code base here.

[DanielPuthawala]

Here's two more mock-ups that are a bit more exploratory.

This first demo is for a protein sequence variant, specifically for a variation in amino acid sequence, rather than being predicted from a nucleotide sequence variant. This example is adapted from variant 627218 from the same Clinvar dataset linked above. As a sequence variant, it has much in common with the canonical allele example earlier.

This second mockup is for a functional variant, here for "BRCA1 Loss-of-function", adapted from this record in CIViC. This mockup incudes an additional functionConstraint which functions similarly to the copyConstraint in the categoricalCNV example above.

[DanielPuthawala]

I should add that the italicized bits, like "Allele" for the defining context and "123456789 for the code are simply placeholders!

[DanielPuthawala]

I've made a minor tweak to the Protein Sequence Consequence variant demo and some more major revisions to the Function Variant demo.

The PSC demo was just tweaked to include relations that make more sense for a variant label that denotes a amino acid sequence change. So rather than something like genomeLiftover we have an example mapping like codonAlignment.

The Function Variant demo has been tweaked more extensively.

First, given that vrs:allele described nucleotide location-states, and functional variants pertain more to protein function, it seems reasonable to assume that the context of a function variant is a gene, rather than a vrs:allele.

Second, the functionConstraint has been updated. First, the values of functionalConsequence has been updated to reflect Muller's morphs typology of gene product function changes. These values have also been updated with the closest SO codes. For most, there is a close match, such as hypermorphic corresponding to "SO:0001557 polypeptide_gain_of_function_variant". For amorphic and neomorphic, there is not an exact protein-specific concept in SO (that I can find), so I've gone with the closest match: "
SO:0002054 loss_of_function_variant for amorphic, and "SO:0002053 gain_of_function_variant" for neomorphic.

Does this seem reasonable? Is there a better typology of protein function? Is there a better-fitting ontology we should reference than SO? (OR should I talk to SO about getting codes added for amorphic and neomorphic?)

Third, since I have removed the quantityConstraint from being a property of the functionConstraint and made it into a constraint in it's own right, which may very well being the same as the copyConstraint from the categoricalCNV demo previously. Haven't gotten there yet.

Hope to hear your thoughts. I'd like to discuss this at our meeting on 7/3/24

[brendanreardon]

Per the discussion today reflecting on what function may or may not be out of scope for CatVRS, and instead may be in Variant Annotation. I think that these items from the Test Set Variants would be in scope:

• Gain of function
• Loss of Function
• Wild type

And the following would be out of scope

• Conserved Domain Mutation
• Promoter Mutation

Uncertain

• Loss of Heterozygosity (LoH)
• Exon Skipping (e.g., MET Exon 14 skipping)

I agree that having oncogenicity and pathogenicity as being out of scope and moreso being for Variant Annotation makes sense. By this logic, LoH and Exon skipping would also be out of scope, I think, but I could be persuaded either way.

[DanielPuthawala]

Hey @brendanreardon Can you elaborate on the Out-of-scope and uncertain ones?

Promoter Mutation simply seems like a fairly benign variant to me, a location, in this case, some gene's promoter region, and a mutation, or minimally specific sequence variant. Is this label specifically an annotation in some form? Conserved Domain Mutation I can see a bit more, in that the location (which domains are evolutionarily conserved?) is itself the result of a lot of hard looking and analysis at the gene phylogenetically. But that being said it's just some sort of variant at that region, no?

I can see a argument for LoH being excluded, but then it's my impression that that too is used as a categorical variant in these cases. So for example, "PTCH1 loss of heterozygosity was associated with increased duration of therapy"

[DanielPuthawala]

Small update to Function constraint with functionTarget property.

In the 8/27 meeting, it was decided to remove this field on grounds that this probably spills over the line into VA territory, and is therefore probably not in-scope for Cat-VRS.

[brendanreardon]

When thinking about Promoter Mutations, I was considering the cases of annotating with a database such as ENCODE to interpret if a variant is within a promoter region. Leaving it in the category of location though is totally fair, similar to describing a variant by the exon that it is located in.

What you wrote about the Conserved Domain was my exact rationale for it and Promoter Mutations. Would a delineation be...

• Alignment with standards and/or other data to categorize a variant - that would be out-of-scope of CatVRS and would be more for the variant annotation spec. For example, labeling NM_198253.3(TERT):c.-57A>C as a promoter mutation.
• Attaching a constraint when describing a categorical variant, and thus requiring that ... other variants meet that constraint to match. For example, making a categorical variant for TERT promoter mutations with such a constraint.

... maybe I am over complicating the promoter use case because it could be inferred from a variant being in an untranslated region and the cDNA numbering 😵‍💫

As for LoH and exon skipping, the examples above of categorizing individual variants versus applying a constraint (or, in other words, requiring that the condition of LoH or exon skipping is met) captures why I'm uncertain about them, I think. What do you think?

[DanielPuthawala]

I think we're on roughly the same page the way you captured it there.

Deciding if something is a LoH or promoter mutation, and recording the information associated with that classification? Yea, that's VA stuff.

Representing that there is a class of variants called "promoter mutations" or "LoH" variants in an efficiently computable fashion? That's Cat-VRS.

So I reckon that even though there's definite overlap in the domains of variation that Cat-VRS and VA is going to count as in-scope, the purpose for those standards and the kind of information being recorded are going to be very different.

[brendanreardon]

As an FYI to myself (since I am still not entirely comfortable with these terms) and folks looking at these models, Daniel (I assume?) has drafted the information model within the readthedocs site for this project. Larry added that this schema, as used in the Genomic Knowledge pilot builds off of the VRSATILE information model (VRSATILE catvars json, thank you, Larry!!).

Current description of the information model in the CatVar read the docs

Do people feel that these are fair descriptions of each field?

• alternativeLabels (list): List of strings of alternative / alias labels.
  • This field may be subject to change within a given system.
• constraints (list): List of records that contain conditions which must be satisfied for a variant or alteration to match the described categorical variant.
  • The constraints should not be updated for a given id, instead the record should be deprecated and a new one created.
• description (string): A free-text description of the entity.
  • This field may be subject to change within a given system.
• id (string): The logical, unique identifier of the entity in the system record in the string format of {system}:{id} such as clinvar:999.
  • This id should not be updated for a given constraint, instead the record should be deprecated and a new one created.
• extensions (list): System-specific representation of a given categorical variant.
  • This field may be subject to change within a given system (?)
• label (string): Free-text label for the categorical variant, as used by the hosting system. Implementers are encouraged to follow standards (e.g., HGVS) for this field.
  • This field may be subject to change within a given system.
• mappings (list): A list of mappings to concepts in terminologies or concepts in other systems. Each record should contain the fields for "system" (the referenced system), "relation" (exactMatch, relatedMatch, or closeMatch - link to this specification?).
  • This field may be subject to change within a given system.
• members (list): A non-exhaustive list of categorical contextual variants that satisfy the constraints defined for this categorical variant's constraints (as represented within the same system?).
  • This field may be subject to change within a given system.
• type (string): "Categorical Variant"

One question that I have is:

• When should another categorical variant be placed in members instead of mappings, and mappings instead of members? I think that the key differentiators are that members (1) satisfy the same constraints and (2) are within the same system, while mappings can be anything in other systems.

p.s. I can move this into a separate discussion, but I thought that it would be appropriate here to help interpretation with the screenshots of the constraint-based model.

[larrybabb]

@brendanreardon If the table above is meant to depict the VRSATILE schema that I showed then it is missing the very important definingContext field that contains the key constraint for a CanonicalAllele. If it is meant to be the newer Cat-Vrs schema then I think there should be a constraints field that is an array of some kind that could potentially contain the definingContext that is the source for all derived members. But I would verify that second assumption with @DanielPuthawala

[larrybabb]

@DanielPuthawala the contextual variant can be referred to as the assayed variant or the called assayed variant, since it is reasonable to assume all assayed variant calls would be contextual variants. But a contextual variant is really just a variant that can be expressed using VRS. It is a variant that is defined on a unique sequence at a unique location with a unique state (if it's an allele) or unique copy count (if its a copynumbercount) or a unique copy change (if it is a copynumber change), etc...
I've also heard folks refer to assayed or contextual variants as observed variants as well.

[DanielPuthawala]

I believe that that's correct, @larrybabb.

Also the RTD schema at the moment is considerably behind the development and discussion of the constraint model. (and I think is tied to the main 1.x branch. I need to update it.

[DanielPuthawala]

Awesome, great. Thank really clarifies a lot @larrybabb. I belive I'm fully in agreement with your above reply to @brendanreardon.

[brendanreardon]

Thank you both!!

[DanielPuthawala]

Hey all, here's a long overdue update to the categoricalCNV demo, updated after conversation with Beth Pitel.
This version fleshes out the copyConstraint, to include information pertaining to CNVs as CatVars that are often referenced in the literature, FDA indications, etc, and I'd love to get your collective thoughts on this.

Change notes:

• Fleshed out the copyConstraint.
• added the "scale" property in addition to the quantity property on the grounds that CNVs are often reported in terms of different reference scales, including the absolute number of copies, as well as relative copy changes in terms of being an x-fold change, or as the log2 value of the relative change.
• "copychange" started out as something a bit different, but ended up looking almost exactly like what's already in VRS, so it's quite possible we could just ref: that and simplify things a bit.
• added the amplificationThreshold as this is a property whose conventional value changes depending on the gene in question, or may specified on an ad-hoc basis.

[brendanreardon]

Amazing! My only comment, I think, is that it may be worthwhile to generalize "amplificationThreshold" to be "threshold" to allow for thresholds being set for copy deletions. When fold change or log2values are reported for copy number segments, there usually is a specified threshold that a group uses to call low-level loss (sometimes also called shallow deletions) from loss or high-level loss.

This is often done with segmented copy number from next-generation sequencing on total, or non-allele specific, copy number. For example, as discussed in this post on the DepMap (cell line data) forums and in the GENIE data guide for assessing copy number. The relevant bit for log2 ratio thresholds used by GENIE is on page 12 and reads:

Thresholds for identifying gains and losses were set to 0.4 and (-)0.5, respectively; these values were obtained by examining the distribution of log2 ratios to identify peaks associated with copy number states.

p.s. Beth ROCKS! 🪨

[DanielPuthawala]

Oh, and also, the Value in quanity should be 1, and not -1, since the scale is "absoluteCopyNumber". -1 copies of a gene would be... a very interesting clinical case!

[DanielPuthawala]

Updated version of the CatCNV demo with these fixes and tweaks.

[DanielPuthawala]

New updated version of the above, with samplePurity pulled out, and if needed, to be it's own constraint.

[Mrinal-Thomas-Epic]

This is very cool! I'm looking forward to seeing what the ClinVar data looks like when using this. I also have a couple questions (that maybe could be discussed at the next CatVRS call). Sorry if they have already been discussed earlier and I missed it.

1. How do you envision downstream software using the log2Value? Currently, there is no place in VRS to represent a log2Value (do we need to add this to VRS or another GKS area?). I'm not sure if we would be able to compare a VRS CopyChange or CopyCount to a log2Value threshhold.
2. How is a threshold different from a quantity? Does the threshhold need to be a string (rather than integer or range)?
3. Users of CatVRS shouldn't be able to provide combinations of constraints that aren't logically valid together. Does moving away from having separate classes for different types categorical variants (i.e., just CategoricalVariant instead of CategoricalCNV) break this principle, or do you have another way to handle this?

[ahwagner]

The constraint model has been implemented in #50.