1.0.0 Trial Use Review Ballot (November 2024)

[ahwagner]

1.0.0 Trial Use Review Ballot (November 2024) Pre-release

Welcome to the VA-Spec 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:

Domain-agnostic data classes

• Statement [docs] [schema] [example]
• EvidenceLine [docs] [schema] [example]
• Document [docs] [schema] [example]
• Method [docs] [schema] [example]
• DataSet [docs] [schema] [example]
• StudyGroup [docs] [schema]
• Contribution [docs] [schema] [example]
• Agent [docs] [schema] [example]

Domain-specific base profiles:

• VariantPathogenicityProposition [docs] [schema] [example]
• VariantOncogenicityProposition [docs] [schema] [example]
• VariantDiagnosticProposition [docs] [schema] [example]
• VariantPrognosticProposition [docs] [schema] [example]
• VariantTherapeuticResponseProposition [docs] [schema] [example]
• ExperimentalVariantFunctionalImpactProposition [docs] [schema] [example]
• ExperimentalVariantFunctionalImpactStudyResult [docs] [schema] [example]
• CohortAlleleFrequencyStudyResult [docs] [schema] [example]

Background on Propositions (here) and Study Results (here).

Domain-specific data classes:

• Condition [docs] [schema]
• TraitSet [docs] [schema] [example]
• TherapyGroup [docs] [schema] [example]
• Therapeutic [docs] [schema]

---

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

[larrybabb]

Change Contribution.date name and datatype to datetime rather than a date.

While it might seem helpful to allow both date and datetime as permissible content types, I think it would only keep the produced data in non-compatible forms (technically speaking).

IMO, it is quite reasonable to imagine that contributions (or activities) to happen multiple times in a single day from the same agent/contributor on the same data and for the same activityType. If other's assume that to be fair, then I think it is best to allow for the more specfic (or precise) datetime representation. Those that only use the date portion can use the very common practice of defaulting 00:00:000 for the time portion and commuicating that decision to downstream users of their data.

---

Vote up or down if you agree with changing the attribute Contribution.date to Contribution.datetime and changing the associated datatype to the gks-core primitive datatype from date to datetime.

[larrybabb]

Just affirming that we raised this change at the Wed, Dec 4 Cat-VRS meeting and the dozen or so participatants agreed to this change or did not raise any concerns or objections to it. So we will go ahead and make this change.

[larrybabb]

Issue is posted here #240

[korikuzma]

Pages are not displaying any information

A handful of pages in RTD are not displaying any information:

• Domain Entity subclasses: https://va-ga4gh.readthedocs.io/en/1.0.0-ballot.2024-11/core-information-model/entities/domain-entities/index.html
• Propositions: https://va-ga4gh.readthedocs.io/en/1.0.0-ballot.2024-11/base-profiles/statement-profiles.html#variant-oncogenicity-study-proposition
• ACMG/AMP 2015 Community profiles: https://va-ga4gh.readthedocs.io/en/1.0.0-ballot.2024-11/community-profiles/acmg-2015.html#

[larrybabb]

I just fixed these, please verify.

[korikuzma]

Reference implementation (VA-Spec Python) is not referenced

https://va-ga4gh.readthedocs.io/en/1.0.0-ballot.2024-11/reference-implementation.html

I've actually created this Python Reference Implementation: https://github.com/ga4gh/va-spec-python . I will be updating models soon.

[korikuzma]

It's also currently named VA-Spec Python. Should I rename this to VA-Python?

[ahwagner]

It's a good question. I still think there's discussion about naming the whole product something other than VA-Spec. Would like to see a decision on that point before changing the reference implementation software naming.

[larrybabb]

I added a discussion here to see if anyone has the appetite to propose or weigh in a rebranding of VA-Spec. #236

[larrybabb]

not really in scope for this TU ballot

[korikuzma]

Moving coming soon to a different section or removing entirely

@larrybabb had made a comment about "coming soon"s here. I agree with it.

[korikuzma]

Add and update 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.

There is this example, but I believe it is outdated (using properties that are not defined in this class and does not have the required proposition field.

[larrybabb]

out of scope for TU ballot, but a great idea and we should add a ticket. we will add the automation of the example integrations into our MSP tool and complete this in the near future.

[mbrush]

Agreed, and yes - that example predates the move to use Propositions in Statements, and will get updated in time. The text fixture examples that are linked to above are the best we have for now (e.g. here for a Statement example)

[larrybabb]

I did just update the one example to be compliant with the recent changes, but it would be good to have you verify.

[Mrinal-Thomas-Epic]

Requirements for focusAllele within subCohortFrequency

Can focusAllele within members of subCohortFrequency be different from the focusAllele in the parent CohortAlleleFrequencyStudyResult? If so, what does that mean and how different can they be? If not, why allow specifying the allele twice (rather than using a different class for subCohortFrequency members)?

Example:

id: parentStudyResult
focusAllele:
  location:
    sequenceReference:
      id: NC_000001.11
      ...
    start: 1000
    end: 1001
  state:
    type: LiteralSequenceExpression
    sequence: C
specifiedBy: <...>
...

subCohortFrequency:
- id: childStudyResult1
  focusAllele:
    location:
      sequenceReference:
        id: NC_000001.11
        ...
      start: 1005
      end: 1006
    state:
      type: LiteralSequenceExpression
      sequence: T
  ...

- id: childStudyResult2
  ...

[mbrush]

As designed, the focus allele of any subCohortFrequency StudyResult should be the same as in the parent Study Result. The sub-results provide frequency information about the same allele in specific subpopulations. Data about the frequency of a different allele would require creating a separate CAF Study Result entirely. I propose we add recommendations to the documentation / implementation guidance to this effect - unless anyone can think of a use case that would necessitate a different allele in the sub-Result.

@Mrinal-Thomas-Epic I'm not sure it is worth it to define a separate class for Sub-StudyResults if the only difference would be dropping the focusAllele/Variant attribute. And keeping this attribute in provides a way to check that the nested sub Result is about the same allele, and therefore appropriate as a subcohort Result.

[Mrinal-Thomas-Epic]

I think it would be worth it to have some kind of way to drop the requirement of focusAllele on subCohortFrequency. In the best case, implementers are currently specifying redundant information, wasting space and logic in implementations. In the worst case, producers may specify invalid information, so consumers will need to implement logic to validate that the focusAlleles match.

We can organize our classes (with inherits and allOf syntax) to re-use property definitions as much as possible and avoid repetitiveness.

[jsstevenson]

More complex ways of composing study groups

I can't claim credit for this notion, but I've been asked to relay it. The defining characteristics of a StudyGroup are provided as an array in the characteristics property, and are "shared by all members of the StudyGroup, representing a criterion for membership in the group" (source). What if I want to express allele frequency for a cohort where members have either characteristic A or characteristic B? What if I want to say that the members have characteristic A but not characteristic B? And, maniacally, what if I have a cohort consisting of (A and not B) or (C and D)? Are these reasonable concepts to want to represent? And if so, how can StudyGroups be defined now in a way that minimizes API breakage if support for this is introduced in the future?

[mbrush]

Thanks for the comment James. These use cases were indeed considered, and a prior version of the StudyGroup class took a Characteristic object as its value, which included attributes that let us do some the things you describe. (You can get a sense for what this class looked like from the SEPIO model here, on which the core VA model is based). However, because the Characteristic class was not required for initial implementations, the simpler MappableConcept was used in its place. If this is a real need for your (or any) application, let us know and we can propose a more expressive modeling pattern (like SEPIO Characteristic) for review.

[jsstevenson]

Thanks @mbrush. I'm spending part of this week reviewing some of the scientific outputs associated with our project to see if there's a conceivable need at this juncture, but I haven't found anything yet that goes beyond an enumeration of multiple shared traits, which is compatible with the class in its current form.

[Mrinal-Thomas-Epic]

Extend CohortAlleleFrequencyStudyResult to categorical variation (and maybe non-Allele VRS variation)

Currently, the focus of CohortAlleleFrequencyStudyResult is limited to Allele (or IRI reference to Allele). Additionally, "Allele" is in the class and property name (focusAllele).

However, it seems likely that one would want to also track the frequency of CNVs and SVs, most likely as a categorical variation (since its rare to have the exact same CNV or SV). It seems like gnomAD already has frequency data for these types of variants (example).

[mbrush]

Does gnomad ever measure frequency of non-Allele variations? If so, it makes sense to expand the range of the focusAllele attribute (and simultaneously consider changing the name of the attribute, and perhaps the profile, to be consistent with this change . . . e.g. focusVariant).

[rhdolin]

Add rigor to structured terminology

Many attributes of type 'string' should be migrated to type 'coding' (e.g. ConceptMapping.relation), with provision of value sets (e.g. code lists) and a registry of known code systems where possible. I know we've talked about this and it's a recognized issue that is on the backburner, so just thought I'd log it here. I'd suggest looking at the FHIR terminology approach, which has evolved over many years in HL7.

[rhdolin]

Would be useful to further standardize study group characteristics

StudyGroup.characteristics - as a future endeavor, it would be very helpful to flesh out / standardize certain group characteristics, particularly those related to ancestry/race/ethnicity so that we can better compare, for instance, population allele frequencies or polygenic scores.

[rhdolin]

Please add some clarifying text to better differentiate the use of Phenotype vs. TraitSet

Distinction between Phenotype vs. TraitSet is a bit fuzzy. Is the idea that multiple phenotypes are 'OR' (e.g. variant causes phenotype A OR phenotype B) whereas you'd use a TraitSet to express 'AND' (e.g. variant causes trait A AND trait B)?

[ahwagner]

Generalize ancillaryResults and qualityMeasures to all Study Results

Per review with @afrubin on MaveDB.

[afrubin]

This will be a very useful way to communicate relevant values like experimental variability (variance, std error) without being overly prescriptive. Having similar naming conventions/structures across GKS Study Results will also make it easier for implementers and data consumers.

[mbrush]

Agree with the utility of a way to capture this type of information in a consistent way, and agree that if we stick with this pattern as a way to capture additional data items in Study Results, then it makes sense to include them in the generic core model StudyResult class. However, reserving final judgement as I have some questions about the proposed modeling pattern, and how it relates to use and modeling of Extensions. Finally, If we do keep this pattern, I would make the simple change of renaming ancillaryReuslts to ancillaryData - as this object contains additional data items, not additional Study Results.

[korikuzma]

@ahwagner

In MetaKB, we previously used Disease and its aliases/alternativeLabels field for handling alternate names. It appears that Disease has been removed and Condition is now one of: MappableConcept or TraitSet. The MappableConcept does not include an aliases or similar field. Instead, it has mappings where we can store a list of ConceptMapping objects, and within those, aCoding object. If I'm understanding correctly, Coding is intended for source identifiers (like mondo, ncit, etc) rather than aliases.

If this is all accurate, then there is no current way to store a list of aliases other than using the Extension model.

I recognize the value of using an Extension for one-off or implementer-specific fields (such as civic_molecular_profile_score). However, aliases seem like a useful property that many implementers would need. It exists in the VRS Variation models (which is great). So this raises the question of why this property is not available in models such as conditions/therapeutics.

I think I would like to better understand why this was removed and if it'd be possible to reconsider adding this property back. Can you please let me know if I'm missing something?

[ahwagner]

I agree with this. I'm also not a huge fan of alternativeLabels as a field name (currently part of the Entity model). @larrybabb how would you feel about rename from alternativeLabels to aliases, and adding the aliases field to MappableConcept as well, to address what @korikuzma mentioned above?

@korikuzma I ran into this same issue in our examples, and indeed I had to use extensions but would prefer a different mechanism. Here, for example, I created an aliases extension for gene aliases.

[mbrush]

I would be ok with adding aliases to MappableConcept (and a description attribute as well - per Kori's comment below). Noting that if we do, it may make sense to have MappableConcept inherit from Entity, rather than Element - given that it would now share just about all of the attributes on Entity.

Re: consistency in naming (alternativeLabel vs alias) - I lean toward alternativeLabel as IMO it is more clear (you have a label, and then alternativeLabels), and more general (aliases may have community-specific meanings, be unfamiliar to some, and may not make sense for some types of Entities - e.g. it is common to use this term for alternate gene names, but not alternate labels for things like a Method, or a Document, which would inherit this attribute from Entity).

Simplest and clearest in my mind to stick with alternativeLabel - at least on the Entity class. In the context of MappableConcepts / DomainEntities like Genes, we could create an aliases attribute, but I think alternativeLabels is clear enough here. Just my 2c - not wedded to this.

[larrybabb]

I'm of the mindset of not loading up MappableConcept with any more attributes than we already have. I think this data type is meant as a work around for defining the entities that we want to share in our messages but do not want to formalize as Entitys. I think we are dancing around the issue that @mbrush has been raising which is whether MappableConcept is an Entity or an Element.

If we want to have MappableConcept be our generalized structure for any Entity that we do not want to create an explicit subclass for then we should simply have it extend from Entity. If you agree with that then the only argument that remains is whether the attribute should remain alternativeLabel as it is currently defined or renamed to alias. I tend to agree with the generic nature of the attribute name on Entity being alternativeLabel as @mbrush has articulated above, so I think I would be fine with keeping it in the message and letting users map it to terms like 'alias' in their own systems.

[larrybabb]

I realize that the spirit of MappableConcept was born out of the pattern laid out by FHIR's CodeableConcept. In FHIR they did not get as dogmatic about the idea thatCodeableConcepts represented concepts that should be Resources (Entities) vs Generalized Data Types (Elements). They simply created the generalized data type CodeableConcept to deal with the myriad of situations that required folks to share concepts that have established coding authorities and enabled FHIR to not allow all those kinds of concepts to creep into their Resource or Data Type modeling domain.

We've already taken MappableConcept a step farther than FHIR took CodeableConcept, but I do not think we want to really go much further unless we are going to convert it to a MappableConcept entity and allow folks to use it for any entity that may or may not have a coding authority associated to it.

CodeableConcept and MappableConcept were designed with the minimalistic purpose of being able to convey an identifiying primary code and/or a label to represent a concept (period). The idea of providing multiple codes that could be mapped to the label and/or primarycode was a useful add-on that FHIR provided due to requirements they hit. We've added the relation attribute to the mappings to clarify how any mapped codes may truly relate to the primary code or label. I wasn't much of a fan of allowing extensions on the Element subtypes so, at this point, I tend to think that this MappableConcept should be renamed to MappableEntity and we should treat it like all Entity subtypes and it should be used in situations where there isn't a specific entity subclass for the implementer's purpose.

[brendanreardon]

I just noticed that subjectVariant, geneContextQualifier, and objectTherapeutic in VariantTherapeuticResponseProposition are of limit 1..1. Should this instead be a 1..m to allow for statements that involve multiple subjectVariants or objectTherapeutics?

I can imagine that an argument could be made that a statement involving AND conditions on multiple variants could be represented as a single categorical variant. For therapies, do you intend for implementers to link to therapy groups, which then associates to therapies? It looks like therapy group has a minimum set size of 2 though.

p.s. Still wrapping my head around this trial version of va-spec!

[mbrush]

@korikuzma I had thought this is what `grouptType' was for as well, and this is consistent with the value of this field in this example:

However, I want @larrybabb to weigh in, as he told me that TherapyGroup is specifically for cases of combination therapies. And that the CIViC notion of 'substitutes' should be handled by creating separate Statements for each of the individual therapies in a 'substitute group'. I approve of this convention (separate statements for substitutes). But if this is indeed the case it seems we don't need the groupType attribute (as it should always be 'combination') - unless it is there for other purposes?

[mbrush]

@brendanreardon My take is that similar logic applies for sets of variants:

• If the set represents variations whose co-occurrence is associated with a condition, then I think the subject could be represented as VRS Haplotype or Genotype.
• If the set represents variants that fit a Categorical Variation definition (e.g. they map to each other across genome references, or they all result in the same protein change, or they are all missense changes impacting the same exon) - then the relevant CatVRS Categorical Variant model would be used to represent the Statement subject.
• If a data provider wants to say that multiple variants are associated with a condition, but they are completely unrelated and don't fit a Categorical Variation definition - then separate Statements should be made to relate each variant to the condition.

[korikuzma]

@mbrush Ah okay. Ya, that makes sense. I would also be in favor of removing groupType if it will always be combination. Additionally, I'd suggest renaming to include Combination in the name.

[brendanreardon]

@mbrush Thank you so much, especially over the holidays, for those thoughts. Is the primary concept around limits for subjectVariant, geneContextQualifier, and objectTherapeutic being 0..1 or 1..1 that a single object is intended to be passed to these fields, which may then reference 1..n entities? This seems to be how therapies are handled at the moment, with objectTherapeutic accepting 1..1 objects, which can be either a Therapeutic (1..1) or TherapyGroup (2..n).

CIViC got around using lists/arrays for multiple co-occurring variants by implementing molecular profiles, and we'll have to figure something out in CatVRS eventually. Still, it may be worthwhile reconsidering these limits, at least for geneContextQualifier. For example, implementers would want to be able to fill in details for both BCR and ABL1 in VariantTherapeuticResponsePropositions that involve BCR::ABL1, and fusions more generally.

Something that Wes, I think, has said on the cat-vrs calls at times is that the schema should be flexible enough to enable implementers to be as vague or as specific as they want or need to be. You and the va-spec group have been super thoughtful in crafting this version. My worry, as an outsider, about these fields only supporting 1 value per statement is coming from a place of concern that it may be too strict and thus alienate some users.

What do you think?

[mbrush]

Hi Brendan. Your explanation above is well aligned with my thinking, and the rationale for crafting the schema as we did. As for the cardinality of the geneContextQualifier attribute - you raise a scenario that I don't think we considered when we restricted this to having max 1 value. We will discuss how to address this on a upcoming call, or in a dedicated ticket. Thanks!

[korikuzma]

Domain Entity Required Fields

Is there a reason why there are no required fields in the domain entity schemas? https://github.com/ga4gh/va-spec/blob/1.0.0-ballot.2024-11.2/schema/va-spec/base/domain-entities-source.yaml

I would assume that we would want TraitSet.traits and TherapyGroup.therapies to be required.

[Mrinal-Thomas-Epic]

EvidenceLine.TargetProposition vs Statement containing the EvidenceLine

Isn't the TargetProposition implied by the statement's SPOQ most or all of the time? What are some examples where it would be different?

[mbrush]

Yes, this will be the case most of the time. But we have come across exceptions. For example, in CIVIC data there are 'AID' Assertions/Statements where the disease that would be the Proposition object condition is a more general disease (e.g. 'Cancer'), and targetPropositions in many of its 'EID' EvidenceLines refer to a more specific disease that would be their objectConditions (e.g. 'Colorectal Cancer'). Thus resulting in the different propositions for the Statement and Evidence Line.

See https://civicdb.org/assertions/101/summary for an example.

Here, the higher order Assertion/Statement (AID101) reports LMNA::NTRK1 Fusions to be oncogenic for 'Cancer' (a more general disease, the objectCondition of the Statement's Proposition). But this is supported by Evidence Lines such as EID8900 based on studies reporting evidence for oncogenicity of a more specific disease such as 'Colorectal Cancer' - which would be the objectConditon of the target Proposition of an Evidence Line based on EID8900 .

(note that this is my interpretation of how this CIVIC data would be modeled. We haven’t actually finalized any profiles for these Assertions with CIVIC implementers - but this is next on our to do list)

[mbrush]

@Mrinal-Thomas-Epic This diagrammed example (again, not yet officially blessed by VICC/CIViC) of a different CIViC record (AID117) provides another, more detailed example.

[Mrinal-Thomas-Epic]

Thank you for the great example; I can see why this approach makes sense. You can consider this comment resolved (not sure if there is a more official way to mark that)

[korikuzma]

Should MappableConcept have a description?

Wasn't sure if I should put this discussion here or in VRS. Its kind of similar to above comment #234 (reply in thread)

We use MappableConcepts to represent Therapy/Disease/Gene objects. In previous versions, these concepts had a description field which we leveraged. Should we consider adding this field to MappableConcept?

[Mrinal-Thomas-Epic]

I had a related thought. When thinking about implementing a mappable concept for an HGNC gene, should label be the gene symbol or full name? If we wanted both, we could use the description as the full name and label as symbol. I'm assuming we would use the HGNC id as the primaryCode.

[korikuzma]

@Mrinal-Thomas-Epic Alex made this example: https://github.com/ga4gh/gks-core/blob/1.0.0-snapshot.2024-11.2/examples/mappable-concept-gene.yaml . Thanks for pointing this out. When updating our normalizers, I forgot about updating identifier to use primaryCode

[Mrinal-Thomas-Epic]

Penetrance as a percentage or fraction

penetranceQualifier is currently a MappableConcept. However, penetrance is also sometimes reported as a numeric percentage of individuals with the genotype who exhibit the phenotype. How would we represent a numeric percentage in the MappableConcept?

[mbrush]

Good point Mrinal. We could add number as an allowable data type for this qualifier. Or introduce a separate penetranceQuantifier attribute for more quantitative descriptions of penetrance. We can decide which makes the most sense when there is a concrete use case requiring this (let us know if you have one now!)

[korikuzma]

Statement types

@mbrush Why were all statement types changed to Statement? For example, VariantTherapeuticResponseStudyStatement used to have type='VariantTherapeuticResponseStudyStatement' but now it is type='Statement'. Having a more specific type seems more precise/descriptive. I'm currently working on transforming MetaKB source data to VA-Spec models and a more specific type would help make this easier

[korikuzma]

Is it because we now have proposition.type?

[Mrinal-Thomas-Epic]

I agree; having a more specific value in type makes deserialization logic simpler

[mbrush]

@korikuzma @Mrinal-Thomas-Epic . Yes, the idea is that the type on the Statement's Proposition tells you the type of Statement it is. I think @ahwagner felt it was duplicative to also create specific subtypes for Statements - he can weigh in here to confirm / expand on this. That said, I agree with you and think that there are advantages to declaring more specific types on Statements beyond the benefit you have called out – that concern conceptual clarity / consistency, and the ability to more precisely specify constraints within specific types of statements. I anticipate that the spec will evolve to support this type of thing, esp. as we explore modeling frameworks like linkML, even if it is not supported in the current approach.

[Mrinal-Thomas-Epic]

Naming for specifiedBy property

Would something like methodsSpecifiedBy, creationProcess, or generatedFollowing be a better name for the specifiedBy property? These alternatives make it more obvious to readers what the property is being used for.

[Mrinal-Thomas-Epic]

Additional options for hasEvidenceItems

For our use case, we're thinking it would be nice to also have simpler options for hasEvidenceItems. Specifically, it would be nice to be able to have the option to put in a Document (for references to PubMed articles) or a Coding (for references to external DBs). I can see an argument for wrapping the Document or Coding within another Statement, but think that could be more complicated than needed for this simple case

[korikuzma]

@Mrinal-Thomas-Epic

I can see an argument for wrapping the Document or Coding within another Statement, but think that could be more complicated than needed for this simple case

Is there a reason why you would not be able to / want to store Documents in EvidenceLine.reportedIn?

[mbrush]

@Mrinal-Thomas-Epic is the use case you have in mind the ability to point from a Statement directly to a publication that provided evidence used to generate the knowledge expressed in the Statement (without even needing to create an EvidenceLine)? If so, the SEPIO model on which the va-core model is based does have a property to support this (see the page for the hasEvidenceFromSources property here) - which could be pulled into the va-core model.

Keep in mind that the va-core model is a subset of the larger SEPIO model, and va-core right now includes only the minimal classes and properties needed to support the data being produced in initial VA implementations. There are many other properties in this 'upstream' SEPIO model that could be pulled into va-core when a concrete implementation need arises. The SEPIO web documentation here can be consulted to discover new classes or properties that might be useful for a va implementation, which can then be pulled into the va-core model. The Characteristic class that came up in response to James' question above is another example of this.

[Mrinal-Thomas-Epic]

@korikuzma I didn't realize it was inheriting the reportedIn property from InformationEntity. I think that would work for Document, so the only ask is for being able specify a Coding.

For an example scenario, let's say a user is evaluating the pathogenicity of a variant using the ACMG 2015 guidelines. They look at gnomAD and finds that the BA1 criteria is satisfied. I would imagine that we would have a BA1 EvidenceLine that somehow references the gnomAD entry. It doesn't feel right to use an IRI reference if the gnomAD entry is outside of our system (which feels closer to a Coding)

[jsstevenson]

Not sure if this belongs here or somewhere else (and apologies for continuing to draw us well outside of what was hypothetically the "November ballot") but I had a few logistical questions about defining Codings for MappableConcepts.

First, tell me if I'm on the right track. Descriptions for Coding.code and Coding.system are that the code should ideally be a CURIE and the system should be what the CURIE prefix expands to. But these are the values given (roundabout) as examples:

{
    "system": "http://purl.obofoundry.org/so.owl/",
    "code": "SO:0000704"
}

For one thing, I don't think that system value is correct (it 404s). Maybe it's meant to be "http://purl.obolibrary.org/obo/so.owl". Having said that, I'd think in the context of a CURIE that the prefix would actually expand to the beginning of a URI pointing to the particular item as provided by the resource (i.e. SO:0000704 -> http://purl.obolibrary.org/obo/SO_0000704) so the system should actually something like "http://purl.obolibrary.org/obo/SO_".

Assuming that's correct: it seems potentially ambiguous that system seems to be able to fulfill a dual purpose: either, in this case, a link to the general EFO resource/a specific distribution thereof (e.g. "http://www.ebi.ac.uk/efo/efo.owl"), or the beginning of a URI for the specific thing as offered by the resource. IE on the one hand, a complete and sufficient (but general) URI, and on the other, an incomplete and invalid URI that can replace the prefix of the code to form a complete and specific reference. I assume the feeling is that this is less bad than creating distinct classes for these different forms of references.

I'm also wondering whether a system should expressly NOT be an identity resolver service like identifiers.org/bioregistry, e.g. "https://identifiers.org/SO:0000704" or "https://identifiers.org/SO:". Or if it matters at all.

Lastly, the example in the description uses the OBO PURL (persistent/permanent URL) address for the system rather than an alternative. I wonder if it's worth calling out persistence as a desirable attribute of the value in this field description? If I were to naively hop onto identifiers.org, there are a couple provided URI completions that are maybe less likely to be permanent.

[mbrush]

Thanks for this @jsstevenson - all excellent points. I created this PR that fixes the non-resolving url, updates recommendations in attribute descriptions, and explores a couple new attributes that would allow complete specification of prefix and prefix expansion where useful. You can jump here directly to see what the updated Coding definition looks like in its entirety. The changes should address concerns about the "dual purpose" of the Coding.system attribute - and provide clearer guidance on how to populate a Coding object.

Some of issues you raise arise from the fact that we specified the Coding code and system attributes to take advantage of CURIE syntax that is used in ontologies/semantic web/linked data world, while also following FHIR conventions that separate reporting of a naked code and a uri for the code system that provided it. We can certainly do a better job documenting this flexibility for now. But I hope that as the spec matures, we can pick one way to capture Codings and stick with it. Any input / feedback about my PR would be welcome.

[korikuzma]

@mbrush We've been trying to implement Coding in our VICC normalizers, but it's been challenging to determine what values to use for system. Are persistent URLs preferred for this field? If so, which resource/repository is preferred? This kind of makes me wonder if system could support a list of options if there is no preferred choice.

[mbrush]

It's a good question. Infrastructure around terminology systems is entirely separate part of standardization that we haven't really put much thought into. I think we are being flexible/permissive right now and hoping to deal with this in the future. But it is worth a conversation to compare ideas and make a plan at some point soon.

[rhdolin]

Here is a link to the HL7 Clinical Genomics committee approach to code systems - doesn't address all the issues, but might be a good area for collaboration.

[jsstevenson]

Thanks @mbrush -- I think the additional descriptive elements you've added are very helpful, and I appreciate the quick response.