Visual Acuity Archetype Discussion

Clinical
21

Hi Lars,

Great progress. A few more thoughts, if I may…

One of the key considerations in designing this archetype is how we define and represent a single ‘test’. The answer may vary depending on clinical expectations versus implementation and data sharing needs.

From my first principles perspective, a single test should include all variations and results for each eye assessed under a shared protocol or method—captured as multiple events representing each eye/state combination. While this may result in numerous events, it preserves the integrity of one coherent test result set conducted using a single, consistent protocol. That said, I’m also not an expert in eye testing, so maybe we do need to adapt the approach as you suggest.

I remain concerned, conceptually, that modelling each eye as a separate test instance is counterintuitive. It adds complexity for implementers, risks confusion by fragmenting related results, and could compromise clinical safety if test components derived from the same method are stored across separate instances.

Ultimately, what would other ophthalmologists expect? How would a single test typically be recorded on paper? And from a data extraction and querying perspective—particularly for national health records or shared care—what structure would be safest and most intuitive to use at scale?

The original archetype draft included a ‘Test name’ that effectively identified the selected protocol configuration. This ensured results were captured in a clearly defined context, supported coherent ordering and display in user interfaces, and provided essential context when shared with other systems or providers. I think there is value in adding this back in, if it is possible to create a relevant value set. It also fits with other test result archetype design patterns.

The protocol should therefore capture the fixed context or configuration for the test (e.g., chart used). If the chart changes, that likely constitutes a different test altogether. What other protocol-level elements would trigger a new test result definition, as opposed to simply recording parameter variations within a single test?

Within this structure, the ‘state’ attributes could then describe the variable conditions under which each result is captured.

And each full named test result could then comprise multiple events—each event recording results for a particular configuration of the ‘state’ variables, per eye tested.

Silje and I have had similar discussions with a group working on hearing test data—it’s complex! It’s not easy to explain in writing, so hopefully Silje can help convey the idea more clearly when you next meet in person.

I would strongly push for the Eye examined to be mandatory - it makes no sense to record results without stating what eye was examined. If each eye has identical results in a legacy system, even if the eye examined is not identical, then perhaps it could be recorded using a null flavour. However if the results are vary and we are not sure what the results mean, it may be better to record the legacy data simply as a text blob.

Remember this archetype is designed for use in all contexts. If anonymisation of the eye examined for research needs to occur then getting the research data set fit for use should be managed by an external export/process which would include removal of the eye examined data

Again from first principles, so please correct me if I’m wrong, the terms ‘right eye position’ or ‘left eye position’ feel ambiguous to me—position may also refer to the anatomical alignment and orientation of the eye, particularly in relation to the other eye, Also the notion of standard gaze ‘positions’.
Do we need to create a cluster with all the parameters/adjustments described in the trial frame spec you suggested and each type of lens used.
Does ‘Trial frame’ need to be included as part of the naming? Is it considered a recording of subjective refraction results?

If we design the archetype to separate the concepts it does not preclude implementers to present them in a single UI widget. However to conflate value sets for quite separate concepts into a single data point in the archetype is problematic if we need to become more specific in the future. I’d advise against this.
If this was only free text recording against ‘Confounding factors’, this is not such an issue. In principle, the issue of the reliability of the participant is often critical to interpretation of the results eg a child who is distracted or a patient with early dementia. In this situation, the reliability is relevant for the whole test and possibly should be recorded in protocol rather than state!

Hope this is useful food for thought…

Regards

Heather

2 Likes
22

Hi Heather, thank you for your very helpful reply!

I’ll make sure we prioritize these issues today’s meeting and will get get back to you.

About the “Test Name”: I’m just worried about trying to broadly categorize a test that like VA that is inheritely “pick and mix” regarding it’s different components, as trying to pick which concepts should or should not be part of the category definition and pre-coordinating their combinations is a rabbit hole that would be great to avoid.

If I had to choose just 2 concepts to combine with each other in the “test name” categories they would be “Type of Correction” and “Test Distance”, to have categories like “Far Distance vision with own glasses”, but even that may become difficult in cases with 2 correction types such as own glasses + pinhole. Plus we already have 2 seperate elements for these Correction Type and Distance, the latter of which es even able to distance as a quantity and not just “Far”.

Another way to explain my thinking: In my mind each VA test is a Lego house made up of 5-8 components “bricks” and there are many different ways to partly take it apart, so that it is very difficult to agree upon which bricks should “stick together” when being categorized. Depending on the clinical circumstances ophthalologists disagree which combinations of concepts are the “important” ones and should be part of categorical definitions like “Test Name”, i don’t really see any consensus about that is useful to us at the moment.
There was an attempt to design an ophthalmic data exchange standard in the 90s in Germany that came up with 34 different pre-coordinated “Test names” vor VA testing, not ideal if you ask me, and very difficult to agree on whether we should sort VA tests into 4, or 34, or 120 Categories. So my approach with the Archetype was to completely split the VA test up into the “atomic” bricks as these are much easier to agree upon than combinations.. I hope that makes sense.

And if Implementers want a drop down menu of exactly 10 different “types” of VA test by combining 3 concept elements, can’t they construct that on an application level, and each combination is assigned to a specific combination of the 3 elements in the composition?

Or maybe I just need to understand better how such a “Test name” categorization could harmonize with more specific “one-concept”-data elements within the same archetype?
Will keep you up to date on the discussions

again, many thanks, i really appreciate your advice and will rack my brain trying to come up with compromises.

23

Hi Lars,

Again, great discussion

Happy to withdraw that suggestion if it makes no sense to you. The thought was generated by a previous iteration of the archetype containing ‘Test name’ but it actually was a category and may be best represented by events!
Test Name (Optional): The name of the exact visual acuity test performed. This generally represents a broad category of applied refraction. Specific refraction details can be described using ‘Refractive Correction’.
Comment: Details of the exact correction applied, or where multiple corrections should be captured via 'Refractive Correction’.
Choice of:

** Pinhole visual acuity [The test is performed with pinhole refraction applied.]
** Usual corrected visual acuity [The test is performed with the patient’s usual refractive correction i.e spectacles or contact lenses.]
** Best corrected visual acuity [The test is performed with the patient’s optimal refractive correction.]
** Unaided visual acuity [The test was performed without visual aid.]

I assume these concepts are also being considered?

Another way to consider this is to add a ‘Test label’ - ie something the clinician user or system wants to label a particular or commonly used configuration of the ‘bricks’ you describe so that all test configurations of the same kind can be queried or displayed.

Perhaps this is heading in the same direction as your comment below…

We haven’t got an example of this in any other archetype, but may be a useful consideration.

Regards

Heather

24

Hi everyone!

Sorry it took me so long to post the protocol! I thought the call at the end of April was, again, very interesting and constructive and I was especially happy that we had a few more people joining in for the first time, with many different combinations of Clinical/Informatics-Backgrounds.

I just came back from the ARVO conferene in Salt Lake City, where I presented my earlier work on an archetype-like FHIR profile, but as some of you know my conclusion is that the agreement on a common, learning semantic model of things like VA is really the key, independent of which syntax we use to sent the elements back and forth. So I am very happy about anyone willing to argue semantics here, it is exactly what is moving us fowards.

Because clinicians tended to have to leave the call a bit earlier why in the future, I would suggest we discuss the most clinical/semantic questions first, and keep the geeky architectural or syntax-related discussions towards the end - as fun as they are.

Protocol

  • I did a 10 minute Intro Presentation on “Why ophthalmic Archetypes”, which I hope to record as an intro video for others to see before they join in for the first time, just have not gotten around to that
  • Discussed that we should only have notation types in there that we are really sure how to define, these must not be ambiguous
  • Agreed to make which eye mandatory for now, because there are workarounds for legacy data without that info, and making it non-mandatory in the future would not be a breaking change
  • Discussed event structure again, agreed that whatever could reasonably be expected to change between two tests of the same eye should be moved to state, including the chart and Optotypes, as we care more about the behaviour of “state” for repeat measurements than what state semantically represents.
  • Discussed BCVA/BRVA, agreed these are not types of correction but something else, should not conflict with actual types of corrections. Better to have as Coded than as Boolean. Move definitions of BCVA/BRVA to protocol.
  • Discussed “Test name” and i expressed my hesitancy about that, in the call I think we sort of settled on using it but only for something very simple, non-repeatable and non-expandeable like “corrected” or “uncorrected”. I would personally rather not have the element in there but I can’t estimate the difference it makes. Following @heather.leslie’s last reply I think I may hold off on adding it right away, as removing an element is a breaking chance and only adding it is not, maybe it is the best way foward if we wait for a use case to actually need it?
  • We discussed how to deal with derived Values, whether these should get a new composition with a coded element saying “I’m derived”, but I am sort of sceptical of whether that would cause problems in terms of the timeprints, i don’t think i would clinically care when exactly the derivation was performed. Also that would nearly have to be mandatory or a boolean, as an empty “I am derived” element may be ambiguous. I will leave derived elements cluster in there for now, I think it is a good idea to have them side by side in the archetype, was similar for original archetype, although Ian mentioned that that was for some other reasons specific to an implementation in London.

Do remind me in case I forgot something important!

I’ll implement the changes to the Archetype soon and repost it.

Next meeting is on the 29. May, 14:00 CET, see .ics file above. Hope we can also have a first new look at the Intraocular Pressure Archetype then.

Best regards and thank you for all your help!
Lars

25

Thaks Lars,

Just a wee bit of clarification on what I recall to be the idea behind the ‘Derived score’.

This came from the Moorfields openEes system, where, as I recall, as well as the usual Metric Snellen, logmar VA scores, low visual acuity codes, they had a local algorithm which converted all of these into an equivalent numeric score. So this was not about e.g. expressing Snellen as logMar, or vice-versa.

It was implemented in openEYES but I will check if it is still used, as it may be redundant now, or superseded.

26

Hi Ian, thanks for the info1

I was not aware that that was reason behind the derived score elements before you told me, but regardless I think there is very good reason to have the elements for “derived logMAR”, “derived Decimal” etc in the Archtype.

And that is because, as I mentioned earlier, people tend to use multiple different notations depending on the level of the Visual acuity (germany: Decimal, Meter snellen, Qualitative), but both diagram representations or computations based on these values would require conversion (derivation) to another notation, often logMAR. (It is a little bit controversial in which cases this is ok to do)

I know multiple ophthalmic softwares that do this, so they have to store their “derived logMAR” somewhere. I don’t think it would be a good idea to just put them in the normal “Logmar Result” element, as that could make it ambiguous whether that was actually the initial notation used or not.
So I quite like the idea of the derived results having their own data elements, this way there is no ambiguity which original recorded value belongs to the derived result, and the “description of derivation” could be used to document how the derivation was performed.

If you or anyone thinks this is a bad idea please do tell me :wink:

1 Like
27

So here is the newest version,

And here is the list of changes I ended up making, note that the last one is not something we talked about in the meeting but that came from my attempts to map synthetic data to a template

  • Changed Eye(s) examined to Eye examined
  • Changed my mind and removed Fixation Testing (Central, Steady, Maintained?) and other pre-verbal tests, because these 1. Are not really measures of VA. 2. Are not mutually exclusive and 3. Are better off in an own Archetype,
  • Constrained Snellen Ratios to be either Ratio or Fraction
  • Changed “1m-Baseline ETDRS Letters Score” to “ETDRS Letters score”, as “1m Baseline” is in Description/Comment
  • Added “Arbitrary Unit” to numerical results elements, so that I could add reasonable range+decimal place limits – I don’t expect all of these to be accepted to UCUM? Any objections?
  • Removed “Derived Minimum Angle of Resolution – not sufficiently sure if anyone would use it.
  • Moved description of derivation to protocol, but changed occurences to 0…*, to account for multiple derivations (i.e. from decimal to both LogMAR and meter Snellen ratio)
  • Removed “Visual Acuity Score – not sufficiently sure if it would be used, could be added without an issue in the future.
  • Allowed for coded Text in “Comment” Element in addition to free text.
  • Changed BCVA/BRVA comparative classifiers to coded text element instead of Boolean, moved their definitions to protocol.
  • Moved the Following to state, as they can vary from one test to the next: Testing distance, General method, Chart or Card type, Optotype, Optotype presentation modifiers
  • Because we discussed that Booleans are usually not a great idea I reworked the glare light to ancillary lighting coded element, intensity element and ancillary lighting device. This way Brightness Acuity Testing can be recorded.
  • Not great to have just one “device details” element when multiple devices are routinely details, so i suggest this:
  1. Aid device details (what are you looking through)
  2. Stimulus device details (what are you looking at)
  3. Ancillari lighting device details (what is being use to shine light at the eye to make it harder)
  • Added Coded Text option to Ambient lighting element (scotopic/mesopic/photopic), as quantification is often not possible.
  • Added Refractometer-Integrated test to general method, especially as these can be especially unreliable test in my experience.
  • Changed my mind again regarding the “Aid position” clusters. Trying to map synthetic data to these was so unnecessary complex because both the elements as well as the contained values were “hard coded” to be duplicated for R/L. 95-99% of VA tests are monocular, and for all these it is perfectly safe to assume that the correction was in front of the same eye that was being tested. We never say “Right eye corrected with the right part of the own glasses positioned in front of the right eye”. So I joined these back into one cluster and added a “same as eye being tested” coded value to the “in front of which eye” element that can serve as the assumed/default value for 95-99% of VA test. This really cuts down on the complexity, while still supporting explicit right/left handling for binocular tests. Makes the vast majority of tests simpler while not actually adding any real complexity to the binocular ones. Any objections?

I’ll try and work out what is worth discussion in the next meeting, thanks to all for the help, I for one do think we are making progess!

1 Like
28

I hope my emails reached everyone about us rescheduling the monthly online meetings to be at 12:00 noon CEST each last Thursday of the month:, so the next one is still the 25th of june but two hours earlier than we initially planned.

Here is the new .ics-file:
invite.ics (2.9 KB)

Here Is the link to the most recent Draft of the VA Archetype, after the changes mentioned below.

I also started keeping my Archetype drafts in a github Repository. Please do get in touch if you want to collaborate there, or in case you think there are better existing repos to add them to?

So here is my belated update on the last meeting, we were a bit decimated due to public holidays, but had very interesting clinical discussions and an exiting open ophthalmic EHR demo by @Poornachandra

Condensed Minutes from online Meeting on 29.5.2025

  1. Testing Distance: We agreed that categorical description of testing distance (near/intermediate/far) is so widespread that even if we may prefer the precision of a quantitative measure, the Archetype should be able to include coded text for near/intermediate/far.
    Does not make sense to be mutually exclusive with quantitative measures, as it may be sensible to record both “35cm” test distance, and the fact that this was classified as “near”.
    → Split up the testing distance into two elements, one coded text (near/intermediate/far) and one quantitative (m/cm/ft/in)
  2. ETDRS Letter Score: We figured out there may be competing definitions for this term, depending on what distance is seen as the “baseline”. As demonstrated in this table..
    → Adjusted that elements description+comment to this:

Element Name
ETDRS Letter Score
Description
The number of optotypes correctly identified by the patient on a logMAR/ETDRS Chart, including those that are presumed to be readable due to being larger than the smallest line that was read entirely. This includes letters presumed readable at 1m distance.
Comment
Commonly used in study settings. This score describes either the number of optotypes identified (letters read): 1. Out of 30 at 1m distance.
Or 2. Out of 70 at 4m distance. In which case the 30 letters from the 1m distance are added to the result as they are presumed readable.
Typically, an ETDRS letter score of 85 is equivalent to 20/20ft, 1.0 decimal, 0.0 logMAR.
Conversion of this notation requires precise understanding of testing procedures and intended meaning.

  1. EHR demo from Medblocks: @Poornachandra shared their experience implementing their openEHR-based ophthalmic EHR that is already in active use in a well-frequented clinic in rural India. It was extremely interesting to see their software, and thereby the previous archetype versions in action, really pioneering work! We also talked about the challenges, some due to room for improvement in the Archetypes and some due to ophthalmologists preference for free-text entry… so both of that is sort of on us clinicians I guess :wink: It was also very encouraging to hear him say he would like to use the revised versions in the future… Many thanks again for sharing!

  2. “Partial Line” documentation.
    Usually VA is scored based on the smallest line where the patient could still read 60% (sometimes 50%) of letters in that line, that’s what the charts are typically designed for. So it is actually expected that smallest line that still “counts” as bening read may not be not read completely. It adds little information to record “missed a letter in the last line!” explicitely as there is a degree of randomness involved.
    I used to think that adding a little “p” for “partial” to the result in case of a missed letter is just a habit of some german ophthalmologists. But surprisingly the doctors using the Medblocks openEHR in India have been doing the same thing!
    I know that it may feel more precise to record the result based on a single letter being read or not, but it it is not part of the standard scoring algorithm (or ISO norm). This has led to problematic data modelling decisions in softwares in the past as it keeps ophthalmologists wanting to enter letters (p) in the data entry fields for VA, leading to a lot of free text results fields that interpret 0.6p as a string..
    I think there are two options:
    Just have that p go into a coded or free text comment (would be fine)
    OR
    I realized this sematically overlaps with the “Letter Termination Adjustment” element in the previous archetype version (p for partial = negative Letter Termination Adjustment score). In that notation 20/20 -2 means 2 Letters were missed from 20/20 line, but the line still counts as read. Again I think this is non-standard, but people want to use it and it does not hurt anyone as long as it is in a seperate element from the actual result (and not in one string together with it). If “20/20 -2” ≈ “1.0p” why not have an element that accounts for this concept of “missed a letter”, whether it is in numerical or “p” form?
    → As a suggestion; I integrated both of those concepts into a “Letters missed or read in addition to scored line”-Element, which can have either a positive or negative count, which is the same as the “Letter Termination Adjustment”, or a “partial” coded text from the old Archetype. This whole concept is not pleasing to purists, but If ophthalmologists in at least three different nations want to document a similar concept, who am I to say they shouldn’t, as long as it does not result in the main result being free text?

There are still a few less clinical issues that may be more interesting for @ian.mcnicoll @heather.leslie @ian.mcnicoll @siljelb @SevKohler than for most clinicians:

  • @ian.mcnicoll mentioned “referencing” as a way we could maybe deal with the similar definitions of “result” and “derived result” elements.
  • Whether it is better to have two “aided by” Clusters (seperate clusters for left/right) or one with a default value of “the eye being tested” being corrected in monocular tests.
  • Whether we need able to resolve hirarchies between different coded text values in the same element (landold C being a “child” of orientation optotype, sloan letter being a “child” of letter archtype, own glasses being a “child” of the less specific “corrected” value ) perhaps via the SNOMED bindings which we will hopefully have in the future?
  • referencing actual refraction/lensmeter/prescription compositions which may have been recorded in another encounter as the source of the lens values used

I hope it’s OK if we try to not have those technical issues fill out all of thursdays meeting… I do have a few clinical things i would like to discuss beforehand, and would like to start looking closer at the intraocular pressure Archetypes as well.

I’ll sugggest an agenda ahead of time, but I’m totally open for anyone to suggest things we should discuss!
Many thanks to all! :wink:

1 Like
29

Hi Lars,

Sorry I will not make this call as I am on holiday.

I’m not particularly pushing to use archetype references, as this is a pretty obscure part of ADL that we have never found very useful in the past. It was designed so that a set of constraints (like those for VA ‘scores’ could be reused in a different context without duplicating the whole constraint. So actually quite a good fit for this use case but I suspect my modeller colleagues would not be keen, just because it is so obscure.

I don’t have strong feelings either way on the other ‘modelling/technical issues’ that you described.

1 Like
30

Quick Update:

You can find the Meeting Minutes and Recording of the last Meeting here

As discussed there we will gravitate towards having a confluence page as the main page for this collaboration and from now on I will post the minutes there, but we want to do the Issue tracking using Jira.
I’ll set up those pages soon.

By the way: we do want to get the VA Archetype into a formal CKM review, but we figured it may be a good idea to push for the IOP Archetype to go through that process fist as I do think it will be a bit less complex and offer valuable review experience.

So the next Meeting on the 31.7.2025 will focus more on the IOP Archetype (12:00 CEST). I’ll see if I can finish up a draft revision and reach out to glaucoma specialists.