@genspectrum/dashboard-components 0.11.6 → 0.11.7

package/src/preact/mutationsOverTime/mutations-over-time.tsx

@@ -252,7 +252,7 @@ function getDownloadData(filteredData: MutationOverTimeDataMap) {
     return filteredData.getFirstAxisKeys().map((mutation) => {
         return dates.reduce(
             (accumulated, date) => {
-                const proportion = filteredData.get(mutation, date)?.proportion ?? 0;
+                const proportion = filteredData.get(mutation, date)?.proportion ?? '';
                 return {
                     ...accumulated,
                     [date.dateString]: proportion,

package/src/query/queryMutationsOverTime.spec.ts

@@ -100,7 +100,11 @@ describe('queryMutationsOverTime', () => {
         });
 
         expect(mutationOverTimeData.getAsArray()).to.deep.equal([
-            [{ proportion: 0.4, count: 4, totalCount: 11 }, null, null],
+            [
+                { proportion: 0.4, count: 4, totalCount: 11 },
+                { proportion: 0, count: 0, totalCount: 12 },
+                { proportion: 0, count: 0, totalCount: 13 },
+            ],
             [
                 { proportion: 0.1, count: 1, totalCount: 11 },
                 { proportion: 0.2, count: 2, totalCount: 12 },
@@ -177,7 +181,7 @@ describe('queryMutationsOverTime', () => {
                     dateFieldTo: '2023-01-02',
                     fields: [],
                 },
-                response: { data: [{ count: 12 }] },
+                response: { data: [{ count: 0 }] },
             },
             {
                 body: {
@@ -247,7 +251,7 @@ describe('queryMutationsOverTime', () => {
         });
 
         expect(mutationOverTimeData.getAsArray()).to.deep.equal([
-            [{ proportion: 0.4, count: 4, totalCount: 11 }, null, null],
+            [{ proportion: 0.4, count: 4, totalCount: 11 }, null, { proportion: 0, count: 0, totalCount: 13 }],
             [{ proportion: 0.1, count: 1, totalCount: 11 }, null, { proportion: 0.3, count: 3, totalCount: 13 }],
         ]);
 
@@ -688,7 +692,10 @@ describe('queryMutationsOverTime', () => {
         });
 
         expect(mutationOverTimeData.getAsArray()).to.deep.equal([
-            [{ proportion: 0.4, count: 4, totalCount: 11 }, null],
+            [
+                { proportion: 0.4, count: 4, totalCount: 11 },
+                { proportion: 0, count: 0, totalCount: 12 },
+            ],
             [
                 { proportion: 0.1, count: 1, totalCount: 11 },
                 { proportion: 0.2, count: 2, totalCount: 12 },
@@ -734,6 +741,139 @@ describe('queryMutationsOverTime', () => {
         expect(dates.length).toBe(0);
     });
 
+    it('should fill with 0 if the mutation does not exist in a date range but count > 0', async () => {
+        const lapisFilter = { field1: 'value1', field2: 'value2' };
+        const dateField = 'dateField';
+
+        lapisRequestMocks.multipleAggregated([
+            {
+                body: { ...lapisFilter, fields: [dateField] },
+                response: {
+                    data: [
+                        { count: 1, [dateField]: '2023-01-01' },
+                        { count: 1, [dateField]: '2023-01-02' },
+                    ],
+                },
+            },
+            {
+                body: {
+                    ...lapisFilter,
+                    dateFieldFrom: '2023-01-01',
+                    dateFieldTo: '2023-01-01',
+                    fields: [],
+                },
+                response: { data: [{ count: 11 }] },
+            },
+            {
+                body: {
+                    ...lapisFilter,
+                    dateFieldFrom: '2023-01-02',
+                    dateFieldTo: '2023-01-02',
+                    fields: [],
+                },
+                response: { data: [{ count: 11 }] },
+            },
+        ]);
+
+        lapisRequestMocks.multipleMutations(
+            [
+                {
+                    body: {
+                        ...lapisFilter,
+                        dateFieldFrom: '2023-01-01',
+                        dateFieldTo: '2023-01-01',
+                        minProportion: 0.001,
+                    },
+                    response: { data: [getSomeTestMutation(0.1, 1)] },
+                },
+                {
+                    body: {
+                        ...lapisFilter,
+                        dateFieldFrom: '2023-01-02',
+                        dateFieldTo: '2023-01-02',
+                        minProportion: 0.001,
+                    },
+                    response: { data: [] },
+                },
+                {
+                    body: {
+                        ...lapisFilter,
+                        dateFieldFrom: '2023-01-01',
+                        dateFieldTo: '2023-01-02',
+                        minProportion: 0.001,
+                    },
+                    response: {
+                        data: [getSomeTestMutation(0.21, 6)],
+                    },
+                },
+            ],
+            'nucleotide',
+        );
+
+        const { mutationOverTimeData } = await queryMutationsOverTimeData({
+            lapisFilter,
+            sequenceType: 'nucleotide',
+            lapis: DUMMY_LAPIS_URL,
+            lapisDateField: dateField,
+            granularity: 'day',
+        });
+
+        expect(mutationOverTimeData.getAsArray()).to.deep.equal([
+            [
+                { proportion: 0.1, count: 1, totalCount: 11 },
+                { proportion: 0, count: 0, totalCount: 11 },
+            ],
+        ]);
+    });
+
+    it('should return null if count in a date range is 0', async () => {
+        const lapisFilter = { field1: 'value1', field2: 'value2' };
+        const dateField = 'dateField';
+
+        lapisRequestMocks.multipleAggregated([
+            {
+                body: { ...lapisFilter, fields: [dateField] },
+                response: {
+                    data: [{ count: 0, [dateField]: '2023-01-01' }],
+                },
+            },
+            {
+                body: {
+                    ...lapisFilter,
+                    dateFieldFrom: '2023-01-01',
+                    dateFieldTo: '2023-01-01',
+                    fields: [],
+                },
+                response: { data: [{ count: 0 }] },
+            },
+        ]);
+
+        lapisRequestMocks.multipleMutations(
+            [
+                {
+                    body: {
+                        ...lapisFilter,
+                        dateFieldFrom: '2023-01-01',
+                        dateFieldTo: '2023-01-01',
+                        minProportion: 0.001,
+                    },
+                    response: { data: [getSomeTestMutation(0.1, 1)] },
+                },
+            ],
+            'nucleotide',
+        );
+
+        const { mutationOverTimeData } = await queryMutationsOverTimeData({
+            lapisFilter,
+            sequenceType: 'nucleotide',
+            lapis: DUMMY_LAPIS_URL,
+            lapisDateField: dateField,
+            granularity: 'day',
+        });
+
+        expect(mutationOverTimeData.getAsArray()).to.deep.equal([[null]]);
+    });
+
     function getSomeTestMutation(proportion: number, count: number) {
         return {
             mutation: 'sequenceName:A123T',

package/src/query/queryMutationsOverTime.ts

@@ -122,6 +122,7 @@ export async function queryMutationsOverTimeData({
 
         const data = await fetchAndPrepareSubstitutionsOrDeletions(filter, sequenceType).evaluate(lapis, signal);
         const totalCountQuery = await getTotalNumberOfSequencesInDateRange(filter).evaluate(lapis, signal);
+
         return {
             date,
             mutations: data.content,
@@ -244,9 +245,14 @@ export function groupByMutation(
     });
 
     data.forEach((mutationData) => {
+        if (mutationData.totalCount == 0) {
+            return;
+        }
+
+        const date = toTemporal(mutationData.date);
+
         mutationData.mutations.forEach((mutationEntry) => {
             const mutation = toSubstitutionOrDeletion(mutationEntry.mutation);
-            const date = toTemporal(mutationData.date);
 
             if (dataArray.get(mutation, date) !== undefined) {
                 dataArray.set(mutation, date, {
@@ -256,6 +262,16 @@ export function groupByMutation(
                 });
             }
         });
+
+        for (const firstAxisKey of dataArray.getFirstAxisKeys()) {
+            if (dataArray.get(firstAxisKey, date) === null) {
+                dataArray.set(firstAxisKey, date, {
+                    count: 0,
+                    proportion: 0,
+                    totalCount: mutationData.totalCount,
+                });
+            }
+        }
     });
 
     return dataArray;

package/src/web-components/visualization/gs-mutations.stories.ts

@@ -2,18 +2,27 @@ import { expect, fireEvent, waitFor } from '@storybook/test';
 import type { Meta, StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 
-import './gs-mutations';
-import '../app';
 import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
-import { LAPIS_URL, NUCLEOTIDE_INSERTIONS_ENDPOINT, NUCLEOTIDE_MUTATIONS_ENDPOINT } from '../../constants';
+import {
+    AGGREGATED_ENDPOINT,
+    LAPIS_URL,
+    NUCLEOTIDE_INSERTIONS_ENDPOINT,
+    NUCLEOTIDE_MUTATIONS_ENDPOINT,
+} from '../../constants';
+import baselineNucleotideMutations from '../../preact/mutations/__mockData__/baselineNucleotideMutations.json';
 import nucleotideInsertions from '../../preact/mutations/__mockData__/nucleotideInsertions.json';
 import nucleotideMutations from '../../preact/mutations/__mockData__/nucleotideMutations.json';
+import overallVariantCount from '../../preact/mutations/__mockData__/overallVariantCount.json';
 import { type MutationsProps } from '../../preact/mutations/mutations';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 
+import './gs-mutations';
+import '../app';
+
 const codeExample = String.raw`
 <gs-mutations
-    lapisFilter='{ "country": "Switzerland", "pangoLineage": "B.1.1.7", "dateTo": "2022-01-01" }'
+    lapisFilter='{ "country": "Switzerland", "dateTo": "2022-01-01", "pangoLineage": "B.1.1.7"}'
+    baselineLapisFilter='{ "country": "Switzerland", "dateTo": "2022-01-01" }'
     sequenceType="nucleotide"
     views='["grid", "table", "insertions"]'
     width='100%'
@@ -26,6 +35,7 @@ const meta: Meta<Required<MutationsProps>> = {
     component: 'gs-mutations',
     argTypes: {
         lapisFilter: { control: 'object' },
+        baselineLapisFilter: { control: 'object' },
         sequenceType: {
             options: ['nucleotide', 'amino acid'],
             control: { type: 'radio' },
@@ -40,6 +50,7 @@ const meta: Meta<Required<MutationsProps>> = {
     },
     args: {
         lapisFilter: { country: 'Switzerland', pangoLineage: 'B.1.1.7', dateTo: '2022-01-01' },
+        baselineLapisFilter: { country: 'Switzerland', dateTo: '2022-01-01' },
         sequenceType: 'nucleotide',
         views: ['grid', 'table', 'insertions'],
         width: '100%',
@@ -63,6 +74,7 @@ const Template: StoryObj<Required<MutationsProps>> = {
         <gs-app lapis="${LAPIS_URL}">
             <gs-mutations
                 .lapisFilter=${args.lapisFilter}
+                .baselineLapisFilter=${args.baselineLapisFilter}
                 .sequenceType=${args.sequenceType}
                 .views=${args.views}
                 .width=${args.width}
@@ -94,6 +106,37 @@ export const Default: StoryObj<Required<MutationsProps>> = {
                         body: nucleotideMutations,
                     },
                 },
+                {
+                    matcher: {
+                        name: 'baselineNucleotideMutations',
+                        url: NUCLEOTIDE_MUTATIONS_ENDPOINT,
+                        body: {
+                            country: 'Switzerland',
+                            dateTo: '2022-01-01',
+                            minProportion: 0,
+                        },
+                    },
+                    response: {
+                        status: 200,
+                        body: baselineNucleotideMutations,
+                    },
+                },
+                {
+                    matcher: {
+                        name: 'overallVariantCount',
+                        url: AGGREGATED_ENDPOINT,
+                        body: {
+                            country: 'Switzerland',
+                            pangoLineage: 'B.1.1.7',
+                            dateTo: '2022-01-01',
+                            fields: [],
+                        },
+                    },
+                    response: {
+                        status: 200,
+                        body: overallVariantCount,
+                    },
+                },
                 {
                     matcher: {
                         name: 'nucleotideInsertions',
@@ -121,6 +164,21 @@ export const OnTableTab: StoryObj<Required<MutationsProps>> = {
     },
 };
 
+export const OnTableTabWithoutJaccardSimilarity: StoryObj<Required<MutationsProps>> = {
+    ...Default,
+    args: {
+        ...Default.args,
+        baselineLapisFilter: undefined,
+    },
+    play: async ({ canvasElement }) => {
+        const canvas = await withinShadowRoot(canvasElement, 'gs-mutations');
+
+        await waitFor(() => expect(canvas.getByRole('button', { name: 'Table' })).toBeInTheDocument());
+
+        await fireEvent.click(canvas.getByRole('button', { name: 'Table' }));
+    },
+};
+
 export const OnInsertionsTab: StoryObj<Required<MutationsProps>> = {
     ...Default,
     play: async ({ canvasElement }) => {

package/src/web-components/visualization/gs-mutations.tsx

@@ -22,6 +22,29 @@ import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsS
  *
  * The proportion interval filter can be used to filter the displayed mutations on client side.
  *
+ * #### Jaccard Similarity
+ *
+ * If the `baselineLapisFilter` attribute is set,
+ * the [Jaccard similarity](https://en.wikipedia.org/wiki/Jaccard_index) is computed for each mutation.
+ * It is computed as `variantWithMutationCount / (variantCount + mutationCount - variantWithMutationCount)`,
+ * - `variantCount` is the number of sequences of the variant (i.e. the number of sequences that match the `lapisFilter`),
+ * - `mutationCount` is the number of sequences with the mutation
+ *    (i.e. the number of sequences matching the `baselineLapisFilter` that have the mutation),
+ * - `variantWithMutationCount` is the number of sequences that belong to the variant and have the mutation
+ *    (i.e. the `count` value that is shown in the table).
+ *
+ * Typically, this is useful when you query mutations of a certain "variant"
+ * (i.e. a certain lineage or a certain set of mutations).
+ * Then the `baselineLapisFilter` should be the `lapisFilter` but without the lineage or mutations.
+ *
+ * For example:
+ * You are interested in a certain lineage in a certain country: `lapisFilter={country: 'Switzerland', linage: 'XY.1.2.3'}`.
+ * Then the "baseline" should be the same filter but without the lineage: `baselineLapisFilter={country: 'Switzerland'}`.
+ *
+ * Computing the Jaccard similarity is not always meaningful, because you might not have a "variant"
+ * (e.g. when you only query for a certain country).
+ * In this case you can simply omit the `baselineLapisFilter`.
+ *
  * ### Grid View
  *
  * The grid view shows the proportion of each sequence symbol (nucleotide or amino acid) for each position that has a mutation.
@@ -45,6 +68,23 @@ export class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
         aminoAcidInsertions?: string[];
     } = {};
 
+    // prettier-ignore
+    // The multiline union type must not start with `|` because it looks weird in the Storybook docs
+    /**
+     * LAPIS filter to select the mutation counts that are used to compute the Jaccard similarity.
+     * If not provided, the Jaccard similarity is not computed.
+     * For details, see the [Jaccard Similarity](#jaccard-similarity) section in the component description.
+     */
+    @property({ type: Object })
+    baselineLapisFilter:
+        (Record<string, string | string[] | number | null | boolean | undefined> & {
+              nucleotideMutations?: string[];
+              aminoAcidMutations?: string[];
+              nucleotideInsertions?: string[];
+              aminoAcidInsertions?: string[];
+          })
+        | undefined = undefined;
+
     /**
      * The type of the sequence for which the mutations should be shown.
      */
@@ -89,6 +129,7 @@ export class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
                 width={this.width}
                 height={this.height}
                 pageSize={this.pageSize}
+                baselineLapisFilter={this.baselineLapisFilter}
             />
         );
     }
@@ -113,6 +154,9 @@ declare global {
 type LapisFilterMatches = Expect<
     Equals<typeof MutationsComponent.prototype.lapisFilter, MutationsProps['lapisFilter']>
 >;
+type BaselineLapisFilterMatches = Expect<
+    Equals<typeof MutationsComponent.prototype.baselineLapisFilter, MutationsProps['baselineLapisFilter']>
+>;
 type SequenceTypeMatches = Expect<
     Equals<typeof MutationsComponent.prototype.sequenceType, MutationsProps['sequenceType']>
 >;