feat(components): add gs-mutation-cooccurrence component

[fhennig]

resolves #1129

Summary

Adds a new gs-mutation-cooccurrence web component that visualizes mutation co-occurrence patterns across time periods as a heatmap.

Each row represents a unique combination of alleles at the specified positions (using LAPIS aggregated field syntax: [501], S[501], ORF1a[501]). Left columns show the allele at each position; right columns show the proportion of sequences with that pattern per time period, colored by frequency.

Implementation follows the 3-layer architecture:

• CooccurrenceOverTimeDataMap (Map2dBase subclass with own serializer)
• queryMutationCooccurrence (fetchAggregated with position fields)
• CooccurrenceOverTimeGrid (new grid sharing ProportionCell etc.)
• gs-mutation-cooccurrence Lit wrapper

Shared grid pieces (ProportionCell, FeaturesOverTimeGridDisplay, styleGridHeader, getTooltipPosition) extracted from features-over-time-grid into features-over-time-grid-shared so both grids can use them.

Screenshot

PR Checklist

• All necessary documentation has been adapted.
• The implemented feature is covered by an appropriate test.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dashboard-components	Ready	Preview	Aug 25, 2026 10:13am

[fhennig]

It'd be good if we would make a release for this feature: GenSpectrum/LAPIS@bd2c7c8

And then also put the released LAPIS somewhere so it's easier to develop the UI component.

[Copilot]

Pull request overview

Adds a new dashboard web component for visualizing mutation co-occurrence patterns over time as a heatmap/grid, and refactors shared “over-time grid” UI pieces to be reused across components.

Changes:

• Introduces gs-mutation-cooccurrence-over-time (Lit wrapper) and the underlying Preact implementation + stories/mocks.
• Adds queryMutationCooccurrence and CooccurrenceOverTimeDataMap for fetching/structuring co-occurrence data.
• Extracts reusable grid display utilities (cell rendering, tooltip positioning, header styling) and introduces a shared OverTimeGridTooltip.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
components/src/web-components/visualization/index.ts	Exports the new gs-mutation-cooccurrence-over-time web component.
components/src/web-components/visualization/gs-mutation-cooccurrence-over-time.tsx	New Lit web component wrapper passing props into the Preact implementation.
components/src/web-components/visualization/gs-mutation-cooccurrence-over-time.stories.ts	Storybook story + fetch mocks for the web component.
components/src/query/queryMutationCooccurrence.ts	New query that fetches aggregated co-occurrence data and builds an over-time data map.
components/src/preact/queriesOverTime/queries-over-time-grid-tooltip.tsx	Refactors tooltip rendering to use shared OverTimeGridTooltip.
components/src/preact/mutationsOverTime/mutations-over-time-grid-tooltip.tsx	Refactors tooltip rendering to use shared OverTimeGridTooltip.
components/src/preact/mutationCooccurrence/mutation-cooccurrence-over-time.tsx	New Preact visualization (tabs + toolbar + CSV export + grid).
components/src/preact/mutationCooccurrence/mutation-cooccurrence-over-time.stories.tsx	Preact story for the new visualization with fetch mocks.
components/src/preact/mutationCooccurrence/mutation-cooccurrence-grid-tooltip.tsx	New tooltip component for co-occurrence grid cells.
components/src/preact/mutationCooccurrence/mutation-cooccurrence-grid-tooltip.stories.tsx	Storybook stories for the new tooltip component.
components/src/preact/mutationCooccurrence/CooccurrenceOverTimeData.ts	New Map2dBase subclass and serializer for co-occurrence patterns.
components/src/preact/mutationCooccurrence/mockData/cooccurrence.json	Mock aggregated response data used in stories.
components/src/preact/components/over-time-grid-tooltip.tsx	New shared tooltip component used by multiple over-time grids.
components/src/preact/components/features-over-time-grid.tsx	Refactors to import shared grid pieces from features-over-time-grid-shared.
components/src/preact/components/features-over-time-grid-shared.tsx	New shared grid utilities extracted for reuse by multiple grids.
components/src/preact/components/cooccurrence-over-time-grid.tsx	New grid component for rendering co-occurrence patterns over time.
components/.storybook/main.ts	Storybook Vite config change (allowedHosts: true).

Suppressed comments (3)

components/src/preact/mutationCooccurrence/mutation-cooccurrence-grid-tooltip.stories.tsx:31

• MutationCooccurrenceGridTooltipProps requires a positions array, but this story omits it, which will cause a runtime error when the tooltip tries to render positions.map(...).

    args: {
        pattern: { alleles: { '[123]': 'A', '[124]': 'T', '[126]': 'G' } },
        date: weekDate,
        value: null,
    },

components/src/preact/mutationCooccurrence/mutation-cooccurrence-grid-tooltip.stories.tsx:39

• MutationCooccurrenceGridTooltipProps requires a positions array, but this story omits it, which will cause a runtime error when the tooltip tries to render positions.map(...).

    args: {
        pattern: { alleles: { '[123]': null, '[124]': 'T', '[126]': null } },
        date: weekDate,
        value: { type: 'value', count: 5, proportion: 0.024, totalCount: 212 },
    },

components/src/preact/mutationCooccurrence/mutation-cooccurrence-grid-tooltip.stories.tsx:47

• MutationCooccurrenceGridTooltipProps requires a positions array, but this story omits it, which will cause a runtime error when the tooltip tries to render positions.map(...).

    args: {
        pattern: { alleles: { '[123]': 'A', '[124]': 'T', '[126]': 'G' } },
        date: weekDate,
        value: { type: 'belowThreshold', totalCount: 100 },
    },

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

Suppressed comments (1)

components/src/query/queryMutationCooccurrence.ts:167

• This bitmask sorts by which positions are covered, not by the number of covered positions promised by the function contract. For example, with three positions, coverage 100 sorts ahead of 011 even though it covers one position instead of two; bitwise shifts also wrap beyond 31 positions. Sort by the count of non-null symbols instead.

    const coverageBits = (key: string) => {
        const symbols = patternByKey.get(key)!.symbols;
        return positions.reduce((acc, pos, i) => {
            const bit = symbols[pos] !== null ? 1 : 0;
            return acc | (bit << (positions.length - 1 - i));

[fengelniederhammer]

AI: coverageBits uses 1 << (positions.length - 1 - i); JS bitwise ops are 32-bit, so with >31 positions the shift wraps and the sort order breaks silently. It also sorts by which positions are covered (leftmost weighted heaviest: 110 > 101), not by the number of covered positions the doc comment promises. If the intent is "more covered positions first, then count", sort by positions.filter(p => symbols[p] !== null).length instead of a bitmask.

[fhennig]

Yes the logic is weird, something simpler would be good. Maybe we can first sort by covered positions and then just do string sorting within.

[fengelniederhammer]

AI: Test-coverage gaps for the co-occurrence logic — currently only single-date happy path is covered. Consider adding:

• multi-date aggregation (counts summed across dates per pattern)
• pattern sort order (coverage-priority + count tiebreak in sortPatternKeysByCoverageAndCount)
• coverage === 0 -> null and total === 0 -> null cell paths
• formatPosition ([501] -> 501, ORF1a[501] -> ORF1a: 501, non-matching fallthrough)
• getFilteredCooccurrenceData proportion-interval filtering and hideGaps (only story-tested today)

[fhennig]

TBD which of these make sense.

[fengelniederhammer]

The formatting looks a bit weird but I also don't know how to improve it...

[fhennig]

ok let's maybe remove the space, and see what it looks like with 4 digits too (maybe needs to be made smaller in those cases?)

[fengelniederhammer]

Do we also need to limit the number of positions? I can imagine that the component doesn't make much sense with 200 positions either.

[fhennig]

I want to check what it looks like with 20, if that's fine we can use that, if not we can maybe start with a max of 10 for now.