@genspectrum/dashboard-components 0.11.6 → 0.12.0

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/utilEntrypoint.ts

@@ -32,3 +32,5 @@ export type { MapSource } from './preact/map/loadMapSource';
 export type { ConfidenceIntervalMethod } from './preact/shared/charts/confideceInterval';
 
 export type { AxisMax, YAxisMaxConfig } from './preact/shared/charts/getYAxisMax';
+
+export { LocationChangedEvent } from './preact/locationFilter/LocationChangedEvent';

package/src/web-components/input/gs-location-filter.stories.ts

@@ -15,7 +15,7 @@ import { withinShadowRoot } from '../withinShadowRoot.story';
 const codeExample = String.raw`
 <gs-location-filter
     fields='["region", "country"]'
-    initialValue='Europe / Switzerland'
+    value='{ "region": "Europe", "country": null}'
     width="100%"
     placeholderText="Enter a location"
 ></gs-location-filter>`;
@@ -39,9 +39,9 @@ const meta: Meta = {
                 type: 'object',
             },
         },
-        initialValue: {
+        value: {
             control: {
-                type: 'text',
+                type: 'object',
             },
         },
         width: {
@@ -66,7 +66,7 @@ const Template: StoryObj<LocationFilterProps> = {
             <div class="max-w-screen-lg">
                 <gs-location-filter
                     .fields=${args.fields}
-                    initialValue=${ifDefined(args.initialValue)}
+                    .value=${args.value}
                     .width=${args.width}
                     placeholderText=${ifDefined(args.placeholderText)}
                 ></gs-location-filter>
@@ -75,7 +75,7 @@ const Template: StoryObj<LocationFilterProps> = {
     },
     args: {
         fields: ['region', 'country', 'division', 'location'],
-        initialValue: '',
+        value: undefined,
         width: '100%',
         placeholderText: 'Enter a location',
     },
@@ -107,10 +107,7 @@ export const LocationFilter: StoryObj<LocationFilterProps> = {
     play: async ({ canvasElement }) => {
         const canvas = await withinShadowRoot(canvasElement, 'gs-location-filter');
         await waitFor(() => {
-            return expect(canvas.getByRole('combobox')).toBeEnabled();
-        });
-        await waitFor(() => {
-            return expect(canvas.getByPlaceholderText('Enter a location')).toBeInTheDocument();
+            return expect(canvas.getByPlaceholderText('Enter a location')).toBeVisible();
         });
     },
 };
@@ -199,36 +196,44 @@ export const FiresEvent: StoryObj<LocationFilterProps> = {
 
         await step('Empty input', async () => {
             await userEvent.type(inputField(), '{backspace>18/}');
-            await expect(listenerMock.mock.calls.at(-1)![0].detail).toStrictEqual({
-                region: undefined,
-                country: undefined,
-                division: undefined,
-                location: undefined,
+            await userEvent.click(canvas.getByLabelText('toggle menu'));
+
+            await waitFor(() => {
+                return expect(listenerMock.mock.calls.at(-1)![0].detail).toStrictEqual({
+                    region: undefined,
+                    country: undefined,
+                    division: undefined,
+                    location: undefined,
+                });
             });
         });
 
         await step('Select Asia', async () => {
             await userEvent.type(inputField(), 'Asia');
-            await expect(listenerMock.mock.calls.at(-1)![0].detail).toStrictEqual({
-                region: 'Asia',
-                country: undefined,
-                division: undefined,
-                location: undefined,
+            await userEvent.click(canvas.getByRole('option', { name: 'Asia Asia' }));
+
+            await waitFor(() => {
+                return expect(listenerMock.mock.calls.at(-1)![0].detail).toStrictEqual({
+                    region: 'Asia',
+                    country: undefined,
+                    division: undefined,
+                    location: undefined,
+                });
             });
         });
 
         await step('Select Asia / Bangladesh / Rajshahi / Chapainawabgonj', async () => {
             await userEvent.type(inputField(), ' / Bangladesh / Rajshahi / Chapainawabgonj');
-            await expect(listenerMock).toHaveBeenCalledWith(
-                expect.objectContaining({
-                    detail: {
-                        region: 'Asia',
-                        country: 'Bangladesh',
-                        division: 'Rajshahi',
-                        location: 'Chapainawabgonj',
-                    },
-                }),
-            );
+            await userEvent.click(canvas.getByText('Asia / Bangladesh / Rajshahi / Chapainawabgonj'));
+
+            await waitFor(() => {
+                return expect(listenerMock.mock.calls.at(-1)![0].detail).toStrictEqual({
+                    region: 'Asia',
+                    country: 'Bangladesh',
+                    division: 'Rajshahi',
+                    location: 'Chapainawabgonj',
+                });
+            });
         });
     },
 };

package/src/web-components/input/gs-location-filter.tsx

@@ -1,6 +1,7 @@
 import { customElement, property } from 'lit/decorators.js';
 import type { DetailedHTMLProps, HTMLAttributes } from 'react';
 
+import { type LocationChangedEvent } from '../../preact/locationFilter/LocationChangedEvent';
 import { LocationFilter, type LocationFilterProps } from '../../preact/locationFilter/location-filter';
 import type { Equals, Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapter } from '../PreactLitAdapter';
@@ -14,11 +15,6 @@ import { PreactLitAdapter } from '../PreactLitAdapter';
  * The component retrieves a list of all possible values for these fields from the Lapis instance.
  * This list is then utilized to display autocomplete suggestions and to validate the input.
  *
- * Given `fields` are `['field1', 'field2', ..., 'fieldN']`,
- * then valid values for the location filter must be in the form `valueForField1 / valueForField2 / ... / valueForFieldK`,
- * where `1 <= K <= N`.
- * Values for the fields `i > K` are considered `undefined`.
- *
  * @fires {CustomEvent<Record<string, string>>} gs-location-changed
  * Fired when a value from the datalist is selected or when a valid value is typed into the field.
  * The `details` of this event contain an object with all `fields` as keys
@@ -37,10 +33,9 @@ import { PreactLitAdapter } from '../PreactLitAdapter';
 export class LocationFilterComponent extends PreactLitAdapter {
     /**
      * The initial value to use for this location filter.
-     * Must be of the form `valueForField1 / valueForField2 / ... / valueForFieldN`.
      */
-    @property()
-    initialValue: string | undefined = undefined;
+    @property({ type: Object })
+    value: Record<string, string | null | undefined> | undefined = undefined;
 
     /**
      * Required.
@@ -70,7 +65,7 @@ export class LocationFilterComponent extends PreactLitAdapter {
     override render() {
         return (
             <LocationFilter
-                initialValue={this.initialValue}
+                value={this.value}
                 fields={this.fields}
                 width={this.width}
                 placeholderText={this.placeholderText}
@@ -85,7 +80,7 @@ declare global {
     }
 
     interface HTMLElementEventMap {
-        'gs-location-changed': CustomEvent<Record<string, string>>;
+        'gs-location-changed': LocationChangedEvent;
     }
 }
 
@@ -99,9 +94,7 @@ declare global {
 }
 
 /* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
-type InitialValueMatches = Expect<
-    Equals<typeof LocationFilterComponent.prototype.initialValue, LocationFilterProps['initialValue']>
->;
+type InitialValueMatches = Expect<Equals<typeof LocationFilterComponent.prototype.value, LocationFilterProps['value']>>;
 type FieldsMatches = Expect<Equals<typeof LocationFilterComponent.prototype.fields, LocationFilterProps['fields']>>;
 type PlaceholderTextMatches = Expect<
     Equals<typeof LocationFilterComponent.prototype.placeholderText, LocationFilterProps['placeholderText']>

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']>
 >;