@genspectrum/dashboard-components 0.11.5 → 0.11.7

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