Show PanelApp mode of inheritance information in variant search results

[tommyli]

Context

Feature request from some of our researchers using MCRI's Seqr instance. They have requested to show PanelApp's "mode
of inheritance" information. Currently, this value is stored as a string in the DB
PaLocusListGene.mode_of_inheritance field. The PanelApp API also returns this value as a string.

Current visual of mouse hover over PanelApp gene list in variant results.

Requirements

Display PanelApp Mode of Inheritance information in variant results.

• On mouse hover over PanelApp gene lists, additional MOI details should be shown similar to the current confidence
  level. Display the raw string from the model/DB.
• Each gene list button/label should provide some kind of visual cue to indicate the MOI info without mouse hover.
• Provide some kind of link out to the gene details page in PanelApp. e.g.
  https://panelapp.agha.umccr.org/panels/92/gene/CASQ2/

Questions for Discussion

1. Will your team be happy for us to implement and raise PR for this?
2. We noticed Seqr's recent integration with GENCC. It's another great resource and we're certainly looking forward
   their upcoming features mentioned in their launch video. We would
   like to understand what your teams' thoughts are regarding how GENCC and PanelApp will integrate together with Seqr,
   current and future plans. E.g. they both share some common information, confidence, MOI, some concept of a gene list
   but not sure if GENCC should supersede PA or remain complementary.

Design/Implementation Discussion

Discussing with some of our researchers, the raw PanelApp text can be categorised into types using below logic. This
type would be used by the UI to provide some kind of visual cue. This type is also convenient for searching/filtering
on in the future. @david-ma from our team will provide additional details for the UI. Note, we've only analysed data
for PanelApp AU, will do so for PanelApp UK and report any additional findings.

class MoiType(Enum):
    BIALLELIC = 'BIALLELIC'
    IMPRINTED_MATERNALY_EXPRESSED = 'IMPRINTED_MATERNALY_EXPRESSED'
    IMPRINTED_PATERNALY_EXPRESSED = 'IMPRINTED_PATERNALY_EXPRESSED'
    MITOCHONDRIAL = 'MITOCHONDRIAL'
    MONOALLELIC = 'MONOALLELIC'
    OTHER = 'OTHER'
    UNKNOWN = 'UNKNOWN'
    X_LINKED_DOMINANT = 'X_LINKED_DOMINANT'
    X_LINKED_RECESSIVE = 'X_LINKED_RECESSIVE'

def moi_to_moi_types(moi):
    if not moi:
        return [MoiType.UNKNOWN]

    if re.match(r'MONOALLELIC.*PATERNALLY IMPRINTED.*', moi.upper()):
        return [MoiType.IMPRINTED_PATERNALY_EXPRESSED]
    elif re.match(r'MONOALLELIC.*MATERNALLY IMPRINTED.*', moi.upper()):
        return [MoiType.IMPRINTED_MATERNALY_EXPRESSED]
    elif re.match(r'X-LINKED:.*BIALLELIC MUTATIONS.*', moi.upper()):
        return [MoiType.X_LINKED_RECESSIVE]
    elif re.match(r'X-LINKED:.*MONOALLELIC MUTATIONS.*', moi.upper()):
        return [MoiType.X_LINKED_RECESSIVE, MoiType.X_LINKED_DOMINANT]
    elif moi.upper().startswith('BIALLELIC'):
        return [MoiType.BIALLELIC]
    elif moi.upper().startswith('MONOALLELIC'):
        return [MoiType.MONOALLELIC]
    elif moi.upper().startswith('BOTH'):
        return [MoiType.BIALLELIC, MoiType.MONOALLELIC]
    elif moi.upper().startswith('MITOCHONDRIAL'):
        return [MoiType.MITOCHONDRIAL]
    elif moi.upper() == 'OTHER':
        return [MoiType.OTHER]
    elif moi.upper() == 'UNKNOWN':
        return [MoiType.UNKNOWN]
    else:
        return [MoiType.OTHER]

The link out URL can be provided by the server using logic similar to below:

if hasattr(locus_list, 'palocuslist'):
    list_url = locus_list.palocuslist.url
    pagene_url = '{}/gene/{}'.format(list_url.replace('/api/v1', '').replace('/genes', ''), gene_json['geneSymbol'])

Above logic can be implemented at the API layer (i.e. at query time) but I was thinking to do this at insert time, i.e
when we import the panels. It'll require new column PaLocusListGene.moi_types_csv (e.g. values can be
"MONOALLELIC", "MITOCHONDRIAL", "BIALLELIC, MONOALLELIC"). The URL logic will remain in the API layer.

Your teams' thoughts/feedback welcome.

[david-ma]

I have investigated a few ideas to display the additional MOI details, and I think the cleanest way is to show PanelApp locus list details in a similar way to OMIM:

A simple alternative is to add the information and the link to the hoverover text, but this link is hard to click on since it's in a hoverover. And there is no indicator to the user of the MOI until each label is hovered, which slows down the workflow.

[hanars]

1. Will your team be happy for us to implement and raise PR for this?

Yes we would. I will have to run the proposed UI by some of our users, but I will let you know in a couple days what they think of the design you propose here, or if they have any other ideas/ preferences. The simple alternative you propose with just adding it the hover is certainly fine to add, the update to show it more like OMIM may be fine (I personally like it) but I would want to confirm that it wouldn't be too visually confusing for users (there is a point where that much information is visually overwhelming and no longer helpful)

2. We noticed Seqr's recent integration with GENCC. It's another great resource and we're certainly looking forward
   their upcoming features mentioned in their launch video. We would
   like to understand what your teams' thoughts are regarding how GENCC and PanelApp will integrate together with Seqr,
   current and future plans. E.g. they both share some common information, confidence, MOI, some concept of a gene list
   but not sure if GENCC should supersede PA or remain complementary.

I consider these to be complimentary resources. In the same way that GenCC and OMIM currently have a lot of overlapping information but are still both valuable, I think Panel APP and GenCC are different enough that it is valuable to display them both separately

Design/Implementation Discussion

Discussing with some of our researchers, the raw PanelApp text can be categorised into types using below logic. This type would be used by the UI to provide some kind of visual cue. ...
Above logic can be implemented at the API layer (i.e. at query time) but I was thinking to do this at insert time, i.e when we import the panels. It'll require new colum

I strongly prefer that UI specific logic lives in UI code, so I would not support implementing that logic at API query time. That said, if you really felt strongly that it be implemented at import time I would consider it an acceptable solution. However, I still think the best solution is just to do the mapping in the UI itself. I don't really see what advantage there is to storing duplicate information in the database and then sending duplicate information in the API response, given that the logic you wrote would have perfectly good performance in javascript. But if you feel strongly that doing this parsing once at import instead of every time on display is worth the database bloat, I would be okay with that

The link out URL can be provided by the server using logic similar to below:

Again, I see no advantage to doing the formatting of the URL in the server. It seems better to return the structured data needed to the UI and then allow the UI to format it as needed. Doing it on the server would be an antipattern to how all other API endpoints work in seqr, including all the ones for GenCC, OMIM, and gene lists

[tommyli]

However, I still think the best solution is just to do the mapping in the UI itself

The reason I see this belonging to the server is because I consider the mapping logic as business logic and thus should remain in the server and closer to the data. Also, if there was a feature in the future to search/filter by this categorised type, would it not be easier if the value was already in the server?

Perhaps my current implementation to do the mapping in the view (query time) will not bloat the DB and still allow the logic to be in one place and reusable by other API clients in the future?

Regarding URL, agree, let's do that in the UI.

[hanars]

After talking with some of the analysts, we think for our use case we would prefer adding it to the hover rather than the OMIM-like approach. We often have several gene lists to a project, so the vertical space needed to show all of them would be too much, or if we added a maximum height with a scroll it would no longer be easy to quickly see all the lists that are included. They also expressed a preference for adding the link to the name of the list itself in the hover, rather than as a separate link on the bottom, to be more consistant with other annotations

[hanars]

What if we used max-height and provide a "Show All" button if there are more than 2 gene lists, which would remove/override the max-height?

So the concern of our analysts is right now if a gene is in 8 lists you can see at one glance that it is in all of them. The OMIM-like proposal removes that ability so instead you can see at a glance the details for 2 lists but for the other 6 lists you can't see if it is in them at all without scrolling/ clicking. For their work, the fact that it is in a list is more important to see quickly than the details of that list, and they worry that they would actually miss the fact that it was in a list entirely

This version uses max-width: 12em; on the labels for more breathing room, and I've added the MOI initials to the MOI description, so the user can see what they mean.

This UI works for our group and we would be happy to upstream it

[david-ma]

On further discussion on the fine tuning of the design here at the MCRI, there are a few points of improvement:

• Having a consistent width would make the PanelApp labels more readable
• Similarly, always having the leading characters be the name of the genelist is better. Eyes don’t need to search as much.
• The initials should be more consistent. AD and AR would be more consistent with the rest of SeqR. E.g. the inheritance search field.


However these mean slightly different things to Monoallelic and Biallelic, which are the raw annotations provided by PanelApp, and it may not be obvious why we are using AD and AR for Monoallelic and Biallelic.


• Unknown does not need to be shown at the “glance” level. It can be shown in the hover-over.
• Only AD, AR, XD and XR are important enough to warrant being displayed up front.

So, perhaps instead of using the initials in brackets, we could use a flag system, like this? This might be more “glanceable” than the initials in brackets. I worry that the font size may be getting a bit too small though.

[hanars]

• Having a consistent width would make the PanelApp labels more readable

I disagree. We have always used min-width instead of width because a lot of trailing color at the end of the label is weird looking. I find the way the non-panel app list here looks to be substantially worse than the previous design. Plus, it unnecessarily wastes horizontal space, and for our projects with over a dozen lists this adds up to a few extra rows of lists, wasting vertical space and making it harder to see everything at a glance. Even making the lists wider is going to end up wasting a lot of space but thats worth it because it adds more visibility to the important label text, but I'm not willing to make that sacrifice for just blank space

• Similarly, always having the leading characters be the name of the genelist is better. Eyes don’t need to search as much.

Agreed

• The initials should be more consistent. AD and AR would be more consistent with the rest of SeqR. E.g. the inheritance search field.

However these mean slightly different things to Monoallelic and Biallelic, which are the raw annotations provided by PanelApp, and it may not be obvious why we are using AD and AR for Monoallelic and Biallelic.


I'm fine with this either way

• Unknown does not need to be shown at the “glance” level. It can be shown in the hover-over.

Agreed

• Only AD, AR, XD and XR are important enough to warrant being displayed up front.

So, perhaps instead of using the initials in brackets, we could use a flag system, like this? This might be more “glanceable” than the initials in brackets. I worry that the font size may be getting a bit too small though.

I find the flags to be incredibly hard to see, this must be in like 3 point font given how small the labels are. While seqr does not technically conform to any formal accessibility standards, anything this small goes against principles of visual accessibility as even someone with perfect vision will struggle to read that. I do like the kind of separate label on the end though but maybe just have it include the text of the MOI in the same fint size as the main label text (i.e. "AD", "AD, AR")

[david-ma]

Having a consistent width would make the PanelApp labels more readable

Sorry, the consistent width doesn't make the labels more readable by itself, but by making the labels line up, so glancing at a group of them is more readable.

But yes you're right, let's just use maxWidth only. Almost all PanelApp genelists are longer than the maxWidth anyway.

[drtconway]

Hi Hannah, Tom from MCRI here.

I agree the AD/AR/etc text is tiny, but there is a rationale: you only have to read it once or twice - after that the position tells you which MOI it is, because the layout is fixed. So as an analyst, you will quickly spot the patterns you care about. The text is important when you're learning, or as a reminder, but from my (limited) experience doing analysis, as you're scanning down the list of variants looking for features to hint you towards deeper investigation/moving on, easy visual cues are really important to help you scan quickly.

That is also the rationale for the fixed width labels, though as David observed, most PanelApp names are long, so it's only going to make a difference in a minority of cases.

I think one minor tweak which might make the visual cue more obvious would be to use grey text rather than black against the white background for "not this MOI".

T.

[hanars]

A question from our analysts - generally speaking how different is the MOI reported in Panel App than the one reported in OMIM?

[tommyli]

Comparing PanelApp AU with our OMIM reference dataset (last updated early this year). Here's a summary.

Here are the total counts of PA genes grouped by moi_types, only selected green genes (confidence level = 3 or 4).

UPDATE: below data was updated after review from @bellmartin, thanks for correcting my mistake in the query!

moi_types	gene_count
BIALLELIC	1953
MONOALLELIC	988
BIALLELIC,MONOALLELIC	534
X_LINKED_RECESSIVE	102
X_LINKED_DOMINANT,X_LINKED_RECESSIVE	95
BIALLELIC,X_LINKED_RECESSIVE	5
MONOALLELIC,X_LINKED_DOMINANT,X_LINKED_RECESSIVE	3
BIALLELIC,MONOALLELIC,X_LINKED_DOMINANT,X_LINKED_RECESSIVE	1
BIALLELIC,X_LINKED_DOMINANT,X_LINKED_RECESSIVE	1

Comparing with OMIM, only these moi_types BIALLELIC, MONOALLELIC, X_LINKED_DOMINANT, X_LINKED_RECESSIVE, BIALLELIC,MONOALLELIC, X_LINKED_RECESSIVE,X_LINKED_DOMINANT were compared and here are the mismatches.

pa_moi_types	gene_mismatches_with_omim
BIALLELIC,MONOALLELIC	177
X_LINKED_DOMINANT,X_LINKED_RECESSIVE	68
BIALLELIC	62
MONOALLELIC	31
X_LINKED_RECESSIVE	5
BIALLELIC,X_LINKED_RECESSIVE	5
MONOALLELIC,X_LINKED_DOMINANT,X_LINKED_RECESSIVE	2
BIALLELIC,X_LINKED_DOMINANT,X_LINKED_RECESSIVE	1

pa_vs_omim.txt
pa_vs_omim_query.txt

[hanars]

thanks this is really helpful!