tooling to auto-generate Defining Location Constraint (bulk Cat-VRS construction)

[Hui-zju]

Feature description

I’m working on batch construction of Cat-VRS CategoricalVariants (potentially at scale for a curated variant set), and I’m still unsure about best practices around building Constraints, especially Defining Location Constraint.

Question / Pain Point

When I decide to use a Defining Location Constraint, I need to construct the Location object(s) precisely (e.g., reference sequence identifiers, coordinate system, normalization behavior, transcript vs genomic context, etc.). In practice this is error-prone for bulk generation.

Is there an existing tool or recommended workflow to automatically generate the Defining Location Constraint content, given higher-level inputs like:

a gene symbol (e.g., PTEN / EGFR),

a transcript accession (optional),

a region description (e.g., “exon 19”, “kinase domain”, “coding region”, “promoter”, “whole gene”, etc.),

or a HGVS-like description / coordinates?

If not currently available:

Feature Request

Would the project consider adding (or recommending) a helper utility / API in the Python reference implementation to generate a valid Defining Location Constraint automatically, for example:

Input: gene symbol + transcript ID + region spec (exon/domain/interval)
Output: a normalized VRS Location (SequenceLocation / ChromosomeLocation) suitable for Defining Location Constraint.

Or Input: HGVS / VCF-like coordinates + assembly
Output: normalized Location object + any required identifiers.

[DanielPuthawala]

Hi there, @Hui-zju, Glad to hear from you!

It sounds like you're trying to construct CategoricalVariant objects given a variety of possible inputs. Some of the ones you mentioned, like a full HGVS expression with coordinates, is potentially precise enough to get exact alleles. For those cases, the VICC Variation Normalizer is a great tool for normalizing those variants, and can provide a VRS:allele version of the variant, which you can then use directly in the DefiningAlleleConstraint in Cat-VRS.

If you have something less specific, such as just a location coordinates, but no Ref or Alt states, then you do have something that can satisfy the DefiningLocationConstraint. I think the VICC Variation normalizer doesn't support that, but I'm almost certain there are other tools in Biocommons or somewhere that can normalize locations and help you generate a VRS:SequenceLocation or other IRI. @korikuzma, and @jsstevenson can you help me out here?

For even less specific inputs, like a Gene symbol or region description, you should instead use the FeatureContextConstraint in Cat-VRS. the FeatureContextConstraint allows for much more flexible but less specific representation without introducing overprecision to your data. So if you know, for example, that the BRAF gene symbol in your data is precisely HGNC:1097 , then you can represent that (name: BRAF, conceptType: Gene, primaryCoding: HGNC:1097) but if you just know it's just a string "BRAF" intended to be a gene symbol, but don't have further provenance on that data, you can literally just use that (name: BRAF, conceptType: Gene).

So to recap the three constraints I mentioned above, here's the basic logic between them:
If you have a molecular location and state (e.g. BRAF V600E) --> DefiningAlleleConstraint
If you only have a sequence coordinated but no state (e.g. BRAF V600) --> DefiningLocationconstraint
If you don't have coordinates (e.g. BRAF) --> FeatureContextConstraint

As for your other question (the actual feature request), if tools don't already exist elsewhere, then that sounds like a decent idea maybe for the Cat-VRS Python reference implementation (eh @korikuzma?).

[jsstevenson]

Yeah, the short answer is -- no, there is no prepackaged tool to do this. It would be nice to add this kind of tooling to cat-vrs-python; the tricky part, of course, is that this usually implies some kinds of external data dependencies, depending on the input (e.g. mappings between genes and locations, if the input is a gene name). I think we'd want to start by talking about specific use cases. In my case, I'm writing software to consume cancer knowledgebase records (like this one) and generate categorical variation objects, so I'd like to be able to ingest a string like "BRAF V600", interpret it in the form "<gene name> <reference protein base><position>", and spit out the corresponding defining location -- but that means I need something like a) a list of legal gene names, b) a mapping between a gene and its corresponding protein accession(s), and c) the raw sequence of the protein accession itself to validate the provided reference. None of that is particularly hard to find, but it can be tricky to package it into open-source software intended for general distribution, so we'll want to be thoughtful about how/whether we do it.

One thing I'll note for clarity (echoing what daniel says above) is that we generally interpret the category "NPM1 Exon 11 Mutation" as FeatureContextConstraint-based, not DefiningLocationConstraint-based; something like BRAF V600 would be a DefiningLocationConstraint. The difference is between "this category consists of anything that happens anywhere on this feature" versus "this category consists of a variant with this specific location and any state".

[Hui-zju]

Hi @DanielPuthawala, @jsstevenson — thanks a lot for the thoughtful replies and for taking the time to lay out the constraint-selection logic so clearly.

Your guidance on choosing among the three constraints is extremely helpful, and I really appreciate the emphasis on avoiding “overprecision” (especially the distinction between FeatureContextConstraint vs DefiningLocationConstraint). The clarification that categories like “NPM1 Exon 11 Mutation” are generally interpreted as FeatureContextConstraint-based (rather than DefiningLocationConstraint-based) is particularly valuable — it helped correct my earlier mental model.

That said, I’d still like to advocate for some kind of repeatable workflow and/or helper tooling for batch generation of Cat-VRS CategoricalVariant objects, because in my experience that’s a key prerequisite for Cat-VRS to be adopted widely in real-world pipelines (e.g., knowledgebase ingestion, cohort annotation, variant catalog curation). Even if a “prepackaged tool” is hard due to external data dependencies (gene↔transcript/protein mappings, reference sequences, etc.), having:

a recommended reference workflow (inputs → recommended constraint type → external dependencies → validation steps), and/or

a minimal set of utilities with pluggable backends (e.g., allow users to provide their own mapping tables / SeqRepo / HGNC resources),
would already lower the barrier a lot for batch use.

On the documentation/examples side, could I also request a FeatureContextConstraint example for a region? Most examples I found focus on Gene features, which led me to initially assume FeatureContextConstraint was “gene-only.” A worked JSON example for something like:

“NPM1 Exon 11 Mutation”
(or any exon/domain/region-style category) would help users understand how to model “this category consists of anything that happens anywhere on this feature (region)” without implying a precise coordinate/location.

Thanks again — really appreciate the direction so far, and excited to help move this toward more scalable, batch-friendly usage.

[DanielPuthawala]

Hi @Hui-zju (and sorry for taking a minute to circle back on this), Thanks for that input!

I've broken out your request for additional examples for the FeatureContextConstraint into a standalone issue here. I think that's an excellent point, a relatively small lift, and definitely something we should add.

As for the reference workflow, while that does sound useful, that's not directly in the scope of our mandate (and manpower) to be able to develop out on our own, but with our commitment to user-driven development, if one or more Cat-VRS adopters are willing to work together to develop such utilities, we'd be overjoyed to endorse such an effort and help make those capabilities available to other potential users!