@genspectrum/dashboard-components 0.13.0 → 0.13.1

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

@@ -0,0 +1,151 @@
+import { type FunctionComponent } from 'preact';
+import { type Dispatch, type StateUpdater, useContext, useState } from 'preact/hooks';
+import z from 'zod';
+
+import { computeWastewaterMutationsOverTimeDataPerLocation } from './computeWastewaterMutationsOverTimeDataPerLocation';
+import { lapisFilterSchema, sequenceTypeSchema } from '../../../types';
+import { LapisUrlContext } from '../../LapisUrlContext';
+import { type ColorScale } from '../../components/color-scale-selector';
+import { ColorScaleSelectorDropdown } from '../../components/color-scale-selector-dropdown';
+import { ErrorBoundary } from '../../components/error-boundary';
+import { Fullscreen } from '../../components/fullscreen';
+import Info, { InfoComponentCode, InfoHeadline1, InfoParagraph } from '../../components/info';
+import { LoadingDisplay } from '../../components/loading-display';
+import { NoDataDisplay } from '../../components/no-data-display';
+import { ResizeContainer } from '../../components/resize-container';
+import Tabs from '../../components/tabs';
+import { type MutationOverTimeDataMap } from '../../mutationsOverTime/MutationOverTimeData';
+import MutationsOverTimeGrid from '../../mutationsOverTime/mutations-over-time-grid';
+import { useQuery } from '../../useQuery';
+
+const wastewaterMutationOverTimeSchema = z.object({
+    lapisFilter: lapisFilterSchema,
+    sequenceType: sequenceTypeSchema,
+    width: z.string(),
+    height: z.string(),
+});
+
+export type WastewaterMutationsOverTimeProps = z.infer<typeof wastewaterMutationOverTimeSchema>;
+
+export const WastewaterMutationsOverTime: FunctionComponent<WastewaterMutationsOverTimeProps> = (componentProps) => {
+    const { width, height } = componentProps;
+    const size = { height, width };
+
+    return (
+        <ErrorBoundary size={size} schema={wastewaterMutationOverTimeSchema} componentProps={componentProps}>
+            <ResizeContainer size={size}>
+                <WastewaterMutationsOverTimeInner {...componentProps} />
+            </ResizeContainer>
+        </ErrorBoundary>
+    );
+};
+
+export const WastewaterMutationsOverTimeInner: FunctionComponent<WastewaterMutationsOverTimeProps> = (
+    componentProps,
+) => {
+    const lapis = useContext(LapisUrlContext);
+
+    const {
+        data: mutationOverTimeDataPerLocation,
+        error,
+        isLoading,
+    } = useQuery(
+        () =>
+            computeWastewaterMutationsOverTimeDataPerLocation(
+                lapis,
+                componentProps.lapisFilter,
+                componentProps.sequenceType,
+            ),
+        [],
+    );
+
+    if (isLoading) {
+        return <LoadingDisplay />;
+    }
+
+    if (error !== null) {
+        throw error;
+    }
+
+    if (mutationOverTimeDataPerLocation.length === 0) {
+        return <NoDataDisplay />;
+    }
+
+    return (
+        <MutationsOverTimeTabs
+            mutationOverTimeDataPerLocation={mutationOverTimeDataPerLocation}
+            originalComponentProps={componentProps}
+        />
+    );
+};
+
+type MutationOverTimeDataPerLocation = {
+    location: string;
+    data: MutationOverTimeDataMap;
+}[];
+
+type MutationOverTimeTabsProps = {
+    mutationOverTimeDataPerLocation: MutationOverTimeDataPerLocation;
+    originalComponentProps: WastewaterMutationsOverTimeProps;
+};
+
+const MutationsOverTimeTabs: FunctionComponent<MutationOverTimeTabsProps> = ({
+    mutationOverTimeDataPerLocation,
+    originalComponentProps,
+}) => {
+    const [colorScale, setColorScale] = useState<ColorScale>({ min: 0, max: 1, color: 'indigo' });
+
+    const tabs = mutationOverTimeDataPerLocation.map(({ location, data }) => ({
+        title: location,
+        content: <MutationsOverTimeGrid data={data} colorScale={colorScale} />,
+    }));
+
+    const toolbar = (
+        <Toolbar
+            colorScale={colorScale}
+            setColorScale={setColorScale}
+            originalComponentProps={originalComponentProps}
+            data={mutationOverTimeDataPerLocation}
+        />
+    );
+
+    return <Tabs tabs={tabs} toolbar={toolbar} />;
+};
+
+type ToolbarProps = {
+    colorScale: ColorScale;
+    setColorScale: Dispatch<StateUpdater<ColorScale>>;
+    originalComponentProps: WastewaterMutationsOverTimeProps;
+    data: MutationOverTimeDataPerLocation;
+};
+
+const Toolbar: FunctionComponent<ToolbarProps> = ({ colorScale, setColorScale, originalComponentProps }) => {
+    return (
+        <>
+            <ColorScaleSelectorDropdown colorScale={colorScale} setColorScale={setColorScale} />
+            <WastewaterMutationsOverTimeInfo originalComponentProps={originalComponentProps} />
+            <Fullscreen />
+        </>
+    );
+};
+
+type WastewaterMutationsOverTimeInfoProps = {
+    originalComponentProps: WastewaterMutationsOverTimeProps;
+};
+
+const WastewaterMutationsOverTimeInfo: FunctionComponent<WastewaterMutationsOverTimeInfoProps> = ({
+    originalComponentProps,
+}) => {
+    const lapis = useContext(LapisUrlContext);
+    return (
+        <Info>
+            <InfoHeadline1>Info for mutations over time</InfoHeadline1>
+            <InfoParagraph> </InfoParagraph>
+            <InfoComponentCode
+                componentName='wastewater-mutations-over-time'
+                params={originalComponentProps}
+                lapisUrl={lapis}
+            />
+        </Info>
+    );
+};

package/src/query/queryMutationsOverTime.ts

@@ -16,14 +16,7 @@ import {
     type SubstitutionOrDeletionEntry,
     type TemporalGranularity,
 } from '../types';
-import { type Map2d } from '../utils/map2d';
-import {
-    type Deletion,
-    type DeletionClass,
-    type Substitution,
-    type SubstitutionClass,
-    toSubstitutionOrDeletion,
-} from '../utils/mutations';
+import { type Deletion, type Substitution, toSubstitutionOrDeletion } from '../utils/mutations';
 import {
     compareTemporal,
     dateRangeCompare,
@@ -41,12 +34,11 @@ export type MutationOverTimeData = {
     totalCount: number;
 };
 
-export type MutationOverTimeMutationValue = { proportion: number; count: number; totalCount: number } | null;
-export type MutationOverTimeDataGroupedByMutation = Map2d<
-    SubstitutionClass | DeletionClass,
-    TemporalClass,
-    MutationOverTimeMutationValue
->;
+export type MutationOverTimeMutationValue = {
+    proportion: number;
+    count: number | null;
+    totalCount: number | null;
+} | null;
 
 const MAX_NUMBER_OF_GRID_COLUMNS = 200;
 

package/src/query/queryWastewaterMutationsOverTime.spec.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+
+import { queryWastewaterMutationsOverTime } from './queryWastewaterMutationsOverTime';
+import { DUMMY_LAPIS_URL, lapisRequestMocks } from '../../vitest.setup';
+import { SubstitutionClass } from '../utils/mutations';
+import { TemporalCache } from '../utils/temporalClass';
+
+const temporalCache = TemporalCache.getInstance();
+
+describe('queryWastewaterMutationsOverTime', () => {
+    it('should fetch data', async () => {
+        const lapisFilter = { country: 'Germany' };
+
+        lapisRequestMocks.details(
+            {
+                country: 'Germany',
+                fields: ['date', 'location', 'nucleotideMutationFrequency', 'aminoAcidMutationFrequency'],
+            },
+            {
+                data: [
+                    {
+                        date: '2021-01-01',
+                        location: 'Germany',
+                        reference: 'organismA',
+                        nucleotideMutationFrequency: JSON.stringify({
+                            A123T: 0.4,
+                            '123G': null,
+                        }),
+                        aminoAcidMutationFrequency: null,
+                    },
+                    {
+                        date: '2021-01-02',
+                        location: 'Germany',
+                        reference: 'organismA',
+                        nucleotideMutationFrequency: null,
+                        aminoAcidMutationFrequency: JSON.stringify({
+                            'S:A123T': 0.4,
+                            'S:123G': 0.1,
+                        }),
+                    },
+                ],
+            },
+        );
+
+        const result = await queryWastewaterMutationsOverTime(DUMMY_LAPIS_URL, lapisFilter);
+
+        expect(result).to.deep.equal([
+            {
+                location: 'Germany',
+                date: temporalCache.getYearMonthDay('2021-01-01'),
+                nucleotideMutationFrequency: [
+                    { mutation: SubstitutionClass.parse('A123T'), proportion: 0.4 },
+                    { mutation: SubstitutionClass.parse('123G'), proportion: null },
+                ],
+                aminoAcidMutationFrequency: [],
+            },
+            {
+                location: 'Germany',
+                date: temporalCache.getYearMonthDay('2021-01-02'),
+                nucleotideMutationFrequency: [],
+                aminoAcidMutationFrequency: [
+                    { mutation: SubstitutionClass.parse('S:A123T'), proportion: 0.4 },
+                    { mutation: SubstitutionClass.parse('S:123G'), proportion: 0.1 },
+                ],
+            },
+        ]);
+    });
+
+    it('should error when the mutation frequency object is invalid', async () => {
+        const lapisFilter = { country: 'Germany' };
+
+        lapisRequestMocks.details(
+            {
+                country: 'Germany',
+                fields: ['date', 'location', 'nucleotideMutationFrequency', 'aminoAcidMutationFrequency'],
+            },
+            {
+                data: [
+                    {
+                        date: '2021-01-01',
+                        location: 'Germany',
+                        reference: 'organismA',
+                        nucleotideMutationFrequency: JSON.stringify({ key: 'not an object of the expected type' }),
+                        aminoAcidMutationFrequency: null,
+                    },
+                ],
+            },
+        );
+
+        await expect(queryWastewaterMutationsOverTime(DUMMY_LAPIS_URL, lapisFilter)).rejects.toThrowError(
+            /^Failed to parse mutation frequency/,
+        );
+    });
+});

package/src/query/queryWastewaterMutationsOverTime.ts

@@ -0,0 +1,55 @@
+import z from 'zod';
+
+import { FetchDetailsOperator } from '../operator/FetchDetailsOperator';
+import { type LapisFilter } from '../types';
+import { type Substitution, SubstitutionClass } from '../utils/mutations';
+import { parseDateStringToTemporal, type TemporalClass, toTemporalClass } from '../utils/temporalClass';
+
+export type WastewaterData = {
+    location: string;
+    date: TemporalClass;
+    nucleotideMutationFrequency: { mutation: Substitution; proportion: number | null }[];
+    aminoAcidMutationFrequency: { mutation: Substitution; proportion: number | null }[];
+}[];
+
+export async function queryWastewaterMutationsOverTime(
+    lapis: string,
+    lapisFilter: LapisFilter,
+    signal?: AbortSignal,
+): Promise<WastewaterData> {
+    const fetchData = new FetchDetailsOperator(lapisFilter, [
+        'date',
+        'location',
+        'nucleotideMutationFrequency',
+        'aminoAcidMutationFrequency',
+    ]);
+    const data = (await fetchData.evaluate(lapis, signal)).content;
+
+    return data.map((row) => ({
+        location: row.location as string,
+        date: toTemporalClass(parseDateStringToTemporal(row.date as string, 'day')),
+        nucleotideMutationFrequency:
+            row.nucleotideMutationFrequency !== null
+                ? transformMutations(JSON.parse(row.nucleotideMutationFrequency as string))
+                : [],
+        aminoAcidMutationFrequency:
+            row.aminoAcidMutationFrequency !== null
+                ? transformMutations(JSON.parse(row.aminoAcidMutationFrequency as string))
+                : [],
+    }));
+}
+
+const mutationFrequencySchema = z.record(z.number().nullable());
+
+function transformMutations(input: unknown): { mutation: Substitution; proportion: number | null }[] {
+    const mutationFrequency = mutationFrequencySchema.safeParse(input);
+
+    if (!mutationFrequency.success) {
+        throw new Error(`Failed to parse mutation frequency: ${mutationFrequency.error.message}`);
+    }
+
+    return Object.entries(mutationFrequency.data).map(([key, value]) => ({
+        mutation: SubstitutionClass.parse(key)!,
+        proportion: value,
+    }));
+}

package/src/utils/map2d.ts

@@ -17,6 +17,8 @@ export interface Map2d<Key1, Key2, Value> {
 
     serializeSecondAxis(key: Key2): string;
 
+    getContents(): Map2DContents<Key1, Key2, Value>;
+
     readonly keysFirstAxis: Map<string, Key1>;
     readonly keysSecondAxis: Map<string, Key2>;
 }
@@ -106,6 +108,35 @@ export class Map2dBase<Key1 extends object | string, Key2 extends object | strin
     }
 }
 
+export class SortedMap2d<Key1 extends object | string, Key2 extends object | string, Value> extends Map2dBase<
+    Key1,
+    Key2,
+    Value
+> {
+    constructor(
+        delegate: Map2d<Key1, Key2, Value>,
+        sortFirstAxis: (a: Key1, b: Key1) => number,
+        sortSecondAxis: (a: Key2, b: Key2) => number,
+    ) {
+        const contents = delegate.getContents();
+        const sortedFirstAxisKeys = new Map(
+            [...contents.keysFirstAxis.entries()].sort((a, b) => sortFirstAxis(a[1], b[1])),
+        );
+        const sortedSecondAxisKeys = new Map(
+            [...contents.keysSecondAxis.entries()].sort((a, b) => sortSecondAxis(a[1], b[1])),
+        );
+        super(
+            (key: Key1) => delegate.serializeFirstAxis(key),
+            (key: Key2) => delegate.serializeSecondAxis(key),
+            {
+                keysFirstAxis: sortedFirstAxisKeys,
+                keysSecondAxis: sortedSecondAxisKeys,
+                data: contents.data,
+            },
+        );
+    }
+}
+
 export class Map2dView<Key1 extends object | string, Key2 extends object | string, Value>
     implements Map2d<Key1, Key2, Value>
 {
@@ -175,4 +206,12 @@ export class Map2dView<Key1 extends object | string, Key2 extends object | strin
 
         return this.baseMap.getRow(key);
     }
+
+    getContents() {
+        return {
+            keysFirstAxis: this.keysFirstAxis,
+            keysSecondAxis: this.keysSecondAxis,
+            data: this.baseMap.getContents().data,
+        };
+    }
 }

package/src/web-components/index.ts

@@ -1,3 +1,4 @@
 export { App } from './app.js';
 export * from './visualization';
+export * from './wastewaterVisualization';
 export * from './input';

package/src/web-components/wastewaterVisualization/gs-wastewater-mutations-over-time.stories.ts

@@ -0,0 +1,82 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { html } from 'lit';
+
+import './gs-wastewater-mutations-over-time';
+import '../app';
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
+import { WISE_DETAILS_ENDPOINT, WISE_LAPIS_URL } from '../../constants';
+import details from '../../preact/wastewater/mutationsOverTime/__mockData__/details.json';
+import { type WastewaterMutationsOverTimeProps } from '../../preact/wastewater/mutationsOverTime/wastewater-mutations-over-time';
+
+const codeExample = String.raw`
+<gs-wastewater-mutations-over-time
+    lapisFilter='{ "dateFrom": "2024-01-01" }'
+    sequenceType='nucleotide'
+    width='100%'
+    height='700px'
+></gs-wastewater-mutations-over-time>`;
+
+const meta: Meta<Required<WastewaterMutationsOverTimeProps>> = {
+    title: 'Wastewater visualization/Wastewater mutations over time',
+    component: 'gs-wastewater-mutations-over-time',
+    argTypes: {
+        lapisFilter: { control: 'object' },
+        sequenceType: {
+            options: ['nucleotide', 'amino acid'],
+            control: { type: 'radio' },
+        },
+        width: { control: 'text' },
+        height: { control: 'text' },
+    },
+    args: {
+        lapisFilter: { versionStatus: 'LATEST_VERSION', isRevocation: false },
+        sequenceType: 'nucleotide',
+        width: '100%',
+        height: '700px',
+    },
+    parameters: withComponentDocs({
+        componentDocs: {
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+        fetchMock: {},
+    }),
+    tags: ['autodocs'],
+};
+
+export default meta;
+
+export const WastewaterMutationsOverTime: StoryObj<Required<WastewaterMutationsOverTimeProps>> = {
+    render: (args) => html`
+        <gs-app lapis="${WISE_LAPIS_URL}">
+            <gs-wastewater-mutations-over-time
+                .lapisFilter=${args.lapisFilter}
+                .sequenceType=${args.sequenceType}
+                .width=${args.width}
+                .height=${args.height}
+            ></gs-wastewater-mutations-over-time>
+        </gs-app>
+    `,
+    parameters: {
+        fetchMock: {
+            mocks: [
+                {
+                    matcher: {
+                        name: 'details',
+                        url: WISE_DETAILS_ENDPOINT,
+                        body: {
+                            fields: ['date', 'location', 'nucleotideMutationFrequency', 'aminoAcidMutationFrequency'],
+                            versionStatus: 'LATEST_VERSION',
+                            isRevocation: false,
+                        },
+                    },
+                    response: {
+                        status: 200,
+                        body: details,
+                    },
+                },
+            ],
+        },
+    },
+};

package/src/web-components/wastewaterVisualization/gs-wastewater-mutations-over-time.tsx

@@ -0,0 +1,112 @@
+import { customElement, property } from 'lit/decorators.js';
+import { type DetailedHTMLProps, type HTMLAttributes } from 'react';
+
+import {
+    WastewaterMutationsOverTime,
+    type WastewaterMutationsOverTimeProps,
+} from '../../preact/wastewater/mutationsOverTime/wastewater-mutations-over-time';
+import { type Equals, type Expect } from '../../utils/typeAssertions';
+import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
+
+/**
+ * ## Context
+ *
+ * This component displays mutations for Swiss wastewater data generated within the WISE consortium. It is designed
+ * only for this purpose and is not designed to be reused outside the WISE project.
+ *
+ * It relies on a LAPIS instance that has the fields `nucleotideMutationFrequency` and `aminoAcidMutationFrequency`.
+ * Those fields are expected to be JSON strings of the format `{ [mutation]: frequency | null }`
+ * (e.g. `{ "A123T": 0.5, "C456G": 0.7, "T789G": null }`).
+ *
+ * The component will stratify by `location`.
+ * Every location will be rendered in a separate tab.
+ * The content of the tab is a "mutations over time" grid, similar to the one used in the `gs-mutations-over-time` component.
+ *
+ * This component also assumes that the LAPIS instance has the field `date` which can be used for the time axis.
+ */
+@customElement('gs-wastewater-mutations-over-time')
+export class WastewaterMutationsOverTimeComponent extends PreactLitAdapterWithGridJsStyles {
+    /**
+     * Required.
+     *
+     * LAPIS filter to select the displayed data.
+     */
+    @property({ type: Object })
+    lapisFilter: Record<string, string | string[] | number | null | boolean | undefined> & {
+        nucleotideMutations?: string[];
+        aminoAcidMutations?: string[];
+        nucleotideInsertions?: string[];
+        aminoAcidInsertions?: string[];
+    } = {};
+
+    /**
+     * Required.
+     *
+     * Whether to display nucleotide or amino acid mutations.
+     */
+    @property({ type: String })
+    sequenceType: 'nucleotide' | 'amino acid' = 'nucleotide';
+
+    /**
+     * The width of the component.
+     *
+     * Visit https://genspectrum.github.io/dashboard-components/?path=/docs/components-size-of-components--docs for more information.
+     */
+    @property({ type: String })
+    width: string = '100%';
+
+    /**
+     * The height of the component.
+     *
+     * Visit https://genspectrum.github.io/dashboard-components/?path=/docs/components-size-of-components--docs for more information.
+     */
+    @property({ type: String })
+    height: string = '700px';
+
+    override render() {
+        return (
+            <WastewaterMutationsOverTime
+                lapisFilter={this.lapisFilter}
+                sequenceType={this.sequenceType}
+                width={this.width}
+                height={this.height}
+            />
+        );
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'gs-wastewater-mutations-over-time': WastewaterMutationsOverTimeComponent;
+    }
+}
+
+declare global {
+    // eslint-disable-next-line @typescript-eslint/no-namespace
+    namespace JSX {
+        interface IntrinsicElements {
+            'gs-wastewater-mutations-over-time': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+        }
+    }
+}
+
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+type LapisFilterMatches = Expect<
+    Equals<
+        typeof WastewaterMutationsOverTimeComponent.prototype.lapisFilter,
+        WastewaterMutationsOverTimeProps['lapisFilter']
+    >
+>;
+type SequenceTypeMatches = Expect<
+    Equals<
+        typeof WastewaterMutationsOverTimeComponent.prototype.sequenceType,
+        WastewaterMutationsOverTimeProps['sequenceType']
+    >
+>;
+type WidthMatches = Expect<
+    Equals<typeof WastewaterMutationsOverTimeComponent.prototype.width, WastewaterMutationsOverTimeProps['width']>
+>;
+type HeightMatches = Expect<
+    Equals<typeof WastewaterMutationsOverTimeComponent.prototype.height, WastewaterMutationsOverTimeProps['height']>
+>;
+/* eslint-enable @typescript-eslint/no-unused-vars, no-unused-vars */

package/src/web-components/wastewaterVisualization/index.ts

@@ -0,0 +1 @@
+export { WastewaterMutationsOverTimeComponent } from './gs-wastewater-mutations-over-time';