1.0.0 Trial Use Review Ballot (November 2024)

[ahwagner]

Welcome to the Cat-VRS Nov '24 Trial Use review

Dear reviewer,

If you are able and willing to participate in the development of these standards, please list individual concerns as separate comments below. All parties are welcome.

Some guidance on creating a comment
Ideally, you should place a Heading tag on the first line of your comment with a summary heading of the specific issue or question (see first comment below as a model). There is no limit to how many comments you can create. It would also be helpful to first look for a similar or related comment and work within the reply thread of that comment if possible.

Thank you for your participation,
The GKS product leads and co-leads

Dates to Remember!

• The ballot review period will begin on Thursday, Nov 28, 2024 and close on Friday, Dec 6, 2024.
• There will be an opportunity for a live feedback and review of the process to be held during the Categorical Variant Meeting on Wednesday, Dec 4, 2024. All VA and Cat-VRS reviewers are welcome to attend.

Implementer Survey (<5mins)

• For all current, future or possible implementers we would like you to also answer this very short survey to indicate which of the Trial Use classes you are most interested in. This will help validate the number of implementers as well as help us keep you informed if future changes occur to your classes of interest. Here are the Implementer's Trial Use Review forms for the VA-Spec and Cat-VRS products, please participate, your contributions help advance the standards and make the process work.

The List of Classes under Consideration

This ballot is a GKS community trial use review for the following classes:

Cat-VRS Base classes

• Categorical Variant [docs] [schema] [example]
• Defining Allele Constraint [docs] [schema] [example]
• Defining Location Constraint [docs] [schema] [example]
• Copy Number Count Constraint [docs] [schema] [example]

Cat-VRS Recipes

• Canonical Allele [docs] [schema] [example]
• Protein Sequence Consequence [docs] [schema] [example]

Join the discussion on this page!

Changelog Since September Connect: 1.0.0-connect.2024-09.1...1.0.0-ballot.2024-11.1

---

This discussion was created from the release 1.0.0 Trial Use Review Ballot (November 2024).

[larrybabb]

CategoricalCnv and CopyNumberChangeConstraint SHOULD be added to the TU review...

Currently, the examples only consider the use of DefiningLocationConstraint and CopyNumberCountConstraint in the context of a CategoricalCnv recipe. If CategoricalCnv is NOT up for trial use consideration then those constraints should be removed. If it is then the CopyNumberChangeConstraint SHOULD also be added to the TU review since it is part of the CategoricalCnv recipe.

[DanielPuthawala]

@ahwagner Can you weigh in on this? Should the CategoricalCNV recipe be on the ballot?

[ahwagner]

IMO the way it is set up now is appropriate for where community implementations are at. Recipes reflect community conventions for certain types of categorical variants, e.g. canonical alleles (NCBI, ClinGen). AFAIK there is no community norm for a categorical CNV. However, there is clearly a need for copy number constraints in ClinVar and some of the VICC KBs.

[brendanreardon]

Adding in that moalmanac, and likely CIViC, is interested in using Categorical CNVs with the GeneContextConstraint instead of DefiningLocationConstraint. The GeneContextConstraint is something that we can resolve in the 1.1 release though, it was a bit sidelined in the relevant discussion thread.

Also echoing that it seems to me to be okay to hold off on adding CategoricalCNV and CopyNumberChangeConstraint until a later release. In the meantime instead, we should add an example(s) from NCBI/ClinGen of adding the CopyNumberCountConstraint to a CanonicalAllele or ProteinSequenceConsequence (I'm guessing that they are using this w.r.t. CanonicalAllele though). I'll take ownership of drafting up an example that meets this criteria.

[korikuzma]

Add Reference implementation to docs

I've created a Python reference implementation here: https://github.com/ga4gh/cat-vrs-python

I will be updating models soon.

[brendanreardon]

Thank you, @korikuzma 🙇! We created an issue to track documentation changes recommended from this ballot, #91.

[korikuzma]

Add examples

One thing I really like about the new docs for VRS, is that it now includes examples. I think it would be really beneficial to users to add examples for each class.

[afrubin]

Thank you for this. The examples are super useful for our project, especially when we are trying to engage with only a subset of the spec (Protein Sequence Consequence) at this stage.

On a related note, the recipe example file is super useful, but it would be great if the vrs.json file that is referenced in the constraints and members sections was also part of the repo for completeness.

[DanielPuthawala]

Like a fully-verbose example that drills down all the way to the GKS.core stuff?

[afrubin]

I think if one complete example was available it would help implementers, since it would be easier to see what CatVRS requires in one place. Having said that, it might be a lot of work if you don't have those files already so it might be out of scope for this TU ballot.

[brendanreardon]

Linking out to this Issue that Daniel created last week to track example updates! #87

[Mrinal-Thomas-Epic]

Should relations be a mappable concept?

Applies to both DefiningAlleleConstraint and DefiningLocationConstraint:

• Do we expect different implementations to define their own types of relations? Wouldn't that defeat the purpose of cat-vrs (to be specific and descriptive about variant matching logic)?
• Do we expect implementations to use the other properties of MappableConcept (i.e., label, mappings, extensions)?

[DanielPuthawala]

I'm not sure we've really settled that question yet. AFAIK the current tack is that we can specify some relations, and adopters have those at a minimum, but could define their own custom relations in addition to the base vanilla ones? @ahwagner and @larrybabb how closely does this reflect your guys' current thinking?

[rhdolin]

Categorical Variant class - minor wordsmithing

"Categorical variants exist solely within genomics knowledgebases" - suggest we broaden this, to something like "Categorical variants exist within genomics knowledgebases, as clinical trial eligibility criteria, and within clinical quality measures".

[brendanreardon]

Totally valid point. Thank you, Bob! We created an issue (#91) to track documentation updates per this ballot, including this thoughtful suggestion.

[rhdolin]

Categorical Variant class - attribute cardinality

1. Consider making categoricalVariant.label required (hard to know what the constraints are constraining otherwise...)
2. categoricalVariant.constraints minimum cardinality should be 1 (why else instantiate the class?)

[DanielPuthawala]

1. I'm not sure we want to do this, since label is usually more of a human-readibility thing, and I can imagine that lots of CatVars in, say, ClinVar, aren't generated with or are even concerned with being human-readible. and so there label would be extraneous. Aside form that, imo the properties of each constriant already record what is being constrained already, be it a location, allele, copy number, etc. That's not to say that you couldn't require label to be populated in a recipe specific to your use-case, though! I'm just not convinced we need it to be required across the board for all use cases.
2. That's not a bad idea. Will have to noodle on this!

[brendanreardon]

As a counter point to requiring minimum cardinality of 1, having the minimum constraints as 0 will allow implementers to pre-allocate and include variant classes that are not yet covered by either cat-vrs or vrs.

For example, if an implementer had a database that contained canonical alleles and other variant types that are covered by vrs/cat-vrs, but also things like... PD-L1 tumor proportion score, they could use the cat-vrs schema for their entire database, not attach any constraints to biomarkers like PD-L1 TPSs, and use extensions to represent the biomarkers as a placeholder.

[rhdolin]

Categorical variant constraints need Boolean operators

categoricalVariant.constraints needs the ability to insert boolean operators (e.g. [constraint A AND (constraint B OR constraint C)]).

[DanielPuthawala]

The system certainly does absolutely require boolean operators (including potentially NOT) somewhere in the system, and this is a puzzle that I have lost a lot of sleep over, but I'm currently leaning in the direction that we would probably be best off building that logic into the recipes, (and maybe within a constraint itself) but not the baseline CategoricalVariant class itself, at least not much.

If a CategoricalVariant has constraints A, B, and C specified in constraints, then you can effectively think of those constraints as all ANDed together. A copy-number gain variant in MET CatVar would have stuff specified for the GeneContextConstraint (MET) and for the CopyCountConstraint, and the members are those contextual variants that are in MET (per the GeneContextConstriant AND constitute a CN-Gain (per the CopyCountConstriant.

However, I can certainly imagine a recipe you might want to specify for a CatVar where there is, for example, a genomic sequence insertion or deletion, but NOT a change in reading frame.

So one way we could imagine doing this would be to specify that a recipe requires that DefiningAlleleConstraint is populated (with appropriate properties), but that the (hypothetical) ReadingFrameConstraint is not populated.

But I think a better way of handling this would be to instead include in ReadingFrameConstraint's properties the option to indicate something like no change to reading frame, because this way, (1) we can distinguish between a CatVar that someone has asserted does not impact reading frame from one where noone has made a claim one way or the other, and (2) In think this approach would maybe let us get away without having to have negation (and associated scoping headaches) in the logic of Cat-VRS. As for AND vs OR logic in recipes, I believe we can already handle these be requiring allOf and anyOf, respectively. But I should probably set aside from time in the future to sit down (the more the merrier) and try to prove to myself that those are all true in all relevant cases...

[rhdolin]

@DanielPuthawala I hadn't seen allOf or anyOf - can you point me to more information on those? But to the bigger question, I understand the value of recipes, but I think the base boolean syntax needs to be defined in the main standard. Have you considered, for instance, that the data type of CategoricalVariant.constraints be 'expression' rather than just a set of constraints? Seems like we can define or draw upon existing specifications to have a simple syntax of combining constraints with AND, OR, NOT, etc.

[rhdolin]

Categorical variant - question about the example

I'm unclear why 'NM_004958.4(MTOR):c.5992_5993del (p.Met1998fs)' is used as an example of a categorical variant. This doesn't look to be a categorical variant.

[DanielPuthawala]

It's a canonical allele, so in addition to the specific contextual variant in the label, it also contains as members congruent variants on other builds etc. But more importantly, it's being represented categorically. Even a singleton set CatVar is still a CatVar.

[rhdolin]

@DanielPuthawala I think it actually makes it harder to describe what a 'categorical variant' is, if a simple variant can be a categorical variant. In the readthedocs, we talk about NC_000007.13:g.140453136A>T vs. BRAF V600E, noting that the latter is a categorical variant. But based on the cited example, so could be the former (e.g. by submitting my assayed variant to ClinVar).

[rhdolin]

Defining Location Constraint - question about the example

Example shows a location constraint with start and end integers, but should probably be start and end ranges.

[rhdolin]

Protein Sequence Consequence - need to have a structured representation of the protein sequence

Example should at lease include a valid pHGVS because as it stands, we only know that this example is for EGFR L858R via the label or alternativeLabels, both of which are text fields.

[afrubin]

The Protein Sequence Consequence includes a DefiningAlleleConstraint that has a VRS allele, but I agree that including a pHGVS somewhere would make sense. Maybe under the extensions section where the CIViC entries are?

Would the pHGVS be a property of the allele object specified in vrs.json per the example?

[rhdolin]

Thanks @afrubin , I missed that. Is there some reason why we can't include a canonical HGVS or SPDI as part of the DefiningAlleleConstraint so that one doesn't have to figure out how to unpack the VRS identifier?

[brendanreardon]

Thank you both! I totally agree, having HGVS representations within the examples should make the implementation more tractable.

Last week Daniel created an issue, #87 about updating the examples and I made a note to add HGVS representations for all examples too. Daniel brought up that the HGVS representations would likely fall under mappings, since it is a representation in another system, but extension would work, too.

[afrubin]

I see the point, but we should definitely only support VRS for the DefiningAlleleConstraint for consistency. Keeping this object minimal is valuable so it's easy to pull out and validate, as adding extra fields that may be in some other format would complicate variant matching and validation. Adding it to mappings makes perfect sense to me.

[ahwagner]

I agree that we should only support VRS Alleles for the defining allele constraint, and will also point out that VRS Alleles have several things that can make downstream implementation easier, including a dedicated datatype (expressions) for other syntax representations that can be added to any variation object under the expressions slot.

For example, here is a VRS variant with a SPDI expression.