@genspectrum/dashboard-components 0.6.2 → 0.6.3

package/src/utils/map2d.spec.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+
+import { Map2d } from './Map2d';
+
+describe('Map2d', () => {
+    it('should add a value and return it', () => {
+        const map2d = new Map2d<string, string, number>();
+        map2d.set('a', 'b', 2);
+        expect(map2d.get('a', 'b')).toBe(2);
+    });
+
+    it('should update a value', () => {
+        const map2d = new Map2d<string, string, number>();
+        map2d.set('a', 'b', 2);
+        map2d.set('a', 'b', 3);
+        expect(map2d.get('a', 'b')).toBe(3);
+    });
+
+    it('should return the data as an array', () => {
+        const map2d = new Map2d<string, string, number>();
+        map2d.set('a', 'b', 1);
+        map2d.set('a', 'd', 2);
+        map2d.set('c', 'b', 3);
+        map2d.set('c', 'd', 4);
+
+        expect(map2d.getAsArray(0)).toEqual([
+            [1, 2],
+            [3, 4],
+        ]);
+    });
+
+    it('should fill empty values with the given value', () => {
+        const map2d = new Map2d<string, string, number>();
+        map2d.set('a', 'b', 2);
+        map2d.set('c', 'd', 4);
+        expect(map2d.getAsArray(0)).toEqual([
+            [2, 0],
+            [0, 4],
+        ]);
+    });
+
+    it('should return the keys from the first axis', () => {
+        const map2d = new Map2d<string, string, number>();
+        map2d.set('a', 'b', 2);
+        map2d.set('c', 'd', 4);
+
+        expect(map2d.getFirstAxisKeys()).toEqual(['a', 'c']);
+    });
+
+    it('should return the keys from the second axis', () => {
+        const map2d = new Map2d<string, string, number>();
+        map2d.set('a', 'b', 2);
+        map2d.set('c', 'd', 4);
+
+        expect(map2d.getSecondAxisKeys()).toEqual(['b', 'd']);
+    });
+
+    it('should work with objects as keys', () => {
+        const map2d = new Map2d<{ a: string }, { b: string }, number>();
+        map2d.set({ a: 'a' }, { b: 'b' }, 2);
+        map2d.set({ a: 'second' }, { b: 'second' }, 3);
+
+        expect(map2d.get({ a: 'a' }, { b: 'b' })).toBe(2);
+        expect(map2d.get({ a: 'second' }, { b: 'second' })).toBe(3);
+    });
+
+    it('should update a value with objects as keys', () => {
+        const map2d = new Map2d<{ a: string }, { b: string }, number>();
+        map2d.set({ a: 'a' }, { b: 'b' }, 2);
+        map2d.set({ a: 'a' }, { b: 'b' }, 3);
+        expect(map2d.get({ a: 'a' }, { b: 'b' })).toBe(3);
+    });
+
+    it('should create a deep copy of the map', () => {
+        const map2d = new Map2d<string, string, number>();
+        map2d.set('a', 'b', 2);
+        expect(map2d.get('a', 'b')).toBe(2);
+
+        const copy = map2d.copy();
+        expect(copy.get('a', 'b')).toBe(2);
+
+        map2d.deleteRow('a');
+        expect(map2d.get('a', 'b')).toBe(undefined);
+    });
+
+    it('should return a row by key', () => {
+        const map2d = new Map2d<string, string, number>();
+        map2d.set('a', 'b', 2);
+        map2d.set('c', 'd', 4);
+
+        expect(map2d.getRow('a', 0)).toEqual([2, 0]);
+        expect(map2d.getRow('c', 0)).toEqual([0, 4]);
+    });
+});

package/src/utils/mutations.ts

@@ -1,9 +1,10 @@
-import { type SequenceType } from '../types';
+import { type MutationType, type SequenceType } from '../types';
 
 export interface Mutation {
     readonly segment: string | undefined;
     readonly position: number;
     readonly code: string;
+    readonly type: MutationType;
 
     equals(other: Mutation): boolean;
 
@@ -15,6 +16,7 @@ export const substitutionRegex =
 
 export class Substitution implements Mutation {
     readonly code;
+    readonly type = 'substitution';
 
     constructor(
         readonly segment: string | undefined,
@@ -62,6 +64,7 @@ export const deletionRegex = /^((?<segment>[A-Za-z0-9_-]+)(?=:):)?(?<valueAtRefe
 
 export class Deletion implements Mutation {
     readonly code;
+    readonly type = 'deletion';
 
     constructor(
         readonly segment: string | undefined,
@@ -103,6 +106,7 @@ export const insertionRegexp =
 
 export class Insertion implements Mutation {
     readonly code;
+    readonly type = 'insertion';
 
     constructor(
         readonly segment: string | undefined,

package/src/utils/temporal.ts

@@ -2,6 +2,8 @@ import dayjs from 'dayjs/esm';
 import advancedFormat from 'dayjs/esm/plugin/advancedFormat';
 import isoWeek from 'dayjs/esm/plugin/isoWeek';
 
+import type { TemporalGranularity } from '../types';
+
 dayjs.extend(isoWeek);
 dayjs.extend(advancedFormat);
 
@@ -70,6 +72,14 @@ export class YearMonthDay {
         return this.text;
     }
 
+    get firstDay(): YearMonthDay {
+        return this;
+    }
+
+    get lastDay(): YearMonthDay {
+        return this;
+    }
+
     get year(): Year {
         return this.cache.getYear(`${this.yearNumber}`);
     }
@@ -124,6 +134,16 @@ export class YearWeek {
         return this.cache.getYearMonthDay(firstDay.format('YYYY-MM-DD'));
     }
 
+    get lastDay(): YearMonthDay {
+        const lastDay = dayjs()
+            .year(this.isoYearNumber)
+            .month(12)
+            .date(31)
+            .isoWeek(this.isoWeekNumber)
+            .endOf('isoWeek');
+        return this.cache.getYearMonthDay(lastDay.format('YYYY-MM-DD'));
+    }
+
     get year(): Year {
         return this.cache.getYear(`${this.isoYearNumber}`);
     }
@@ -163,6 +183,12 @@ export class YearMonth {
         return this.cache.getYearMonthDay(dayjs(`${this.yearNumber}-${this.monthNumber}-01`).format('YYYY-MM-DD'));
     }
 
+    get lastDay(): YearMonthDay {
+        return this.cache.getYearMonthDay(
+            dayjs(`${this.yearNumber}-${this.monthNumber}-01`).endOf('month').format('YYYY-MM-DD'),
+        );
+    }
+
     get year(): Year {
         return this.cache.getYear(`${this.yearNumber}`);
     }
@@ -201,10 +227,18 @@ export class Year {
         return this.cache.getYearMonth(`${this.year}-01`);
     }
 
+    get lastMonth(): YearMonth {
+        return this.cache.getYearMonth(`${this.year}-12`);
+    }
+
     get firstDay(): YearMonthDay {
         return this.firstMonth.firstDay;
     }
 
+    get lastDay(): YearMonthDay {
+        return this.lastMonth.lastDay;
+    }
+
     addYears(years: number): Year {
         const date = this.firstDay.dayjs.add(years, 'year');
         const s = date.format('YYYY');
@@ -311,9 +345,9 @@ export function compareTemporal(a: Temporal | null, b: Temporal | null): number
     return 0;
 }
 
-export function getMinMaxTemporal(values: Iterable<Temporal | null>): [Temporal, Temporal] | null {
-    let min = null;
-    let max = null;
+export function getMinMaxTemporal<T extends Temporal>(values: Iterable<T | null>) {
+    let min: T | null = null;
+    let max: T | null = null;
     for (const value of values) {
         if (value === null) {
             continue;
@@ -326,9 +360,9 @@ export function getMinMaxTemporal(values: Iterable<Temporal | null>): [Temporal,
         }
     }
     if (min === null || max === null) {
-        return null;
+        return { min: null, max: null };
     }
-    return [min, max];
+    return { min, max };
 }
 
 export function addUnit(temporal: Temporal, amount: number): Temporal {
@@ -346,3 +380,28 @@ export function addUnit(temporal: Temporal, amount: number): Temporal {
     }
     throw new Error(`Invalid argument: ${temporal}`);
 }
+
+export function parseDateStringToTemporal(date: string, granularity: TemporalGranularity) {
+    const cache = TemporalCache.getInstance();
+    const day = cache.getYearMonthDay(date);
+    switch (granularity) {
+        case 'day':
+            return day;
+        case 'week':
+            return day.week;
+        case 'month':
+            return day.month;
+        case 'year':
+            return day.year;
+    }
+}
+
+export function dateRangeCompare(a: { dateRange: Temporal | null }, b: { dateRange: Temporal | null }) {
+    if (a.dateRange === null) {
+        return 1;
+    }
+    if (b.dateRange === null) {
+        return -1;
+    }
+    return compareTemporal(a.dateRange, b.dateRange);
+}

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

@@ -0,0 +1,225 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { html } from 'lit';
+
+import './gs-mutations-over-time';
+import '../app';
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
+import { AGGREGATED_ENDPOINT, LAPIS_URL, NUCLEOTIDE_MUTATIONS_ENDPOINT } from '../../constants';
+import aggregated_date from '../../preact/mutationsOverTime/__mockData__/aggregated_date.json';
+import nucleotideMutation_01 from '../../preact/mutationsOverTime/__mockData__/nucleotideMutations_2024_01.json';
+import nucleotideMutation_02 from '../../preact/mutationsOverTime/__mockData__/nucleotideMutations_2024_02.json';
+import nucleotideMutation_03 from '../../preact/mutationsOverTime/__mockData__/nucleotideMutations_2024_03.json';
+import nucleotideMutation_04 from '../../preact/mutationsOverTime/__mockData__/nucleotideMutations_2024_04.json';
+import nucleotideMutation_05 from '../../preact/mutationsOverTime/__mockData__/nucleotideMutations_2024_05.json';
+import nucleotideMutation_06 from '../../preact/mutationsOverTime/__mockData__/nucleotideMutations_2024_06.json';
+import nucleotideMutation_07 from '../../preact/mutationsOverTime/__mockData__/nucleotideMutations_2024_07.json';
+import { type MutationsOverTimeProps } from '../../preact/mutationsOverTime/mutations-over-time';
+
+const codeExample = String.raw`
+<gs-mutations-over-time
+    lapisFilter='{ "pangoLineage": "JN.1*", "dateFrom": "2024-01-15", "dateTo": "2024-07-10" }'
+    sequenceType="nucleotide"
+    views='["grid"]'
+    headline="Mutations over time"
+    width='100%'
+    height='700px'
+    granularity="month"
+    lapisDateField="date"
+></gs-mutations-over-time>`;
+
+const meta: Meta<Required<MutationsOverTimeProps>> = {
+    title: 'Visualization/Mutations over time',
+    component: 'gs-mutations-over-time',
+    argTypes: {
+        lapisFilter: { control: 'object' },
+        sequenceType: {
+            options: ['nucleotide', 'amino acid'],
+            control: { type: 'radio' },
+        },
+        views: {
+            options: ['grid'],
+            control: { type: 'check' },
+        },
+        width: { control: 'text' },
+        height: { control: 'text' },
+        granularity: {
+            options: ['day', 'week', 'month', 'year'],
+            control: { type: 'radio' },
+        },
+        lapisDateField: { control: 'text' },
+    },
+    args: {
+        lapisFilter: { pangoLineage: 'JN.1*', dateFrom: '2024-01-15', dateTo: '2024-07-10' },
+        sequenceType: 'nucleotide',
+        views: ['grid'],
+        width: '100%',
+        height: '700px',
+        granularity: 'month',
+        lapisDateField: 'date',
+    },
+    parameters: withComponentDocs({
+        componentDocs: {
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
+    tags: ['autodocs'],
+};
+
+export default meta;
+
+const Template: StoryObj<Required<MutationsOverTimeProps>> = {
+    render: (args) => html`
+        <gs-app lapis="${LAPIS_URL}">
+            <gs-mutations-over-time
+                .lapisFilter=${args.lapisFilter}
+                .sequenceType=${args.sequenceType}
+                .views=${args.views}
+                .width=${args.width}
+                .height=${args.height}
+                .granularity=${args.granularity}
+                .lapisDateField=${args.lapisDateField}
+            ></gs-mutations-over-time>
+        </gs-app>
+    `,
+};
+
+export const Default: StoryObj<Required<MutationsOverTimeProps>> = {
+    ...Template,
+    parameters: {
+        fetchMock: {
+            mocks: [
+                {
+                    matcher: {
+                        name: 'aggregated_dates',
+                        url: AGGREGATED_ENDPOINT,
+                        body: {
+                            dateFrom: '2024-01-15',
+                            dateTo: '2024-07-10',
+                            fields: ['date'],
+                            pangoLineage: 'JN.1*',
+                        },
+                    },
+                    response: {
+                        status: 200,
+                        body: aggregated_date,
+                    },
+                },
+                {
+                    matcher: {
+                        name: 'nucleotideMutations_01',
+                        url: NUCLEOTIDE_MUTATIONS_ENDPOINT,
+                        body: {
+                            pangoLineage: 'JN.1*',
+                            dateFrom: '2024-01-01',
+                            dateTo: '2024-01-31',
+                            minProportion: 0.001,
+                        },
+                    },
+                    response: {
+                        status: 200,
+                        body: nucleotideMutation_01,
+                    },
+                },
+                {
+                    matcher: {
+                        name: 'nucleotideMutations_02',
+                        url: NUCLEOTIDE_MUTATIONS_ENDPOINT,
+                        body: {
+                            pangoLineage: 'JN.1*',
+                            dateFrom: '2024-02-01',
+                            dateTo: '2024-02-29',
+                            minProportion: 0.001,
+                        },
+                    },
+                    response: {
+                        status: 200,
+                        body: nucleotideMutation_02,
+                    },
+                },
+                {
+                    matcher: {
+                        name: 'nucleotideMutations_03',
+                        url: NUCLEOTIDE_MUTATIONS_ENDPOINT,
+                        body: {
+                            pangoLineage: 'JN.1*',
+                            dateFrom: '2024-03-01',
+                            dateTo: '2024-03-31',
+                            minProportion: 0.001,
+                        },
+                        response: {
+                            status: 200,
+                            body: nucleotideMutation_03,
+                        },
+                    },
+                },
+                {
+                    matcher: {
+                        name: 'nucleotideMutations_04',
+                        url: NUCLEOTIDE_MUTATIONS_ENDPOINT,
+                        body: {
+                            pangoLineage: 'JN.1*',
+                            dateFrom: '2024-04-01',
+                            dateTo: '2024-04-30',
+                            minProportion: 0.001,
+                        },
+                        response: {
+                            status: 200,
+                            body: nucleotideMutation_04,
+                        },
+                    },
+                },
+                {
+                    matcher: {
+                        name: 'nucleotideMutations_05',
+                        url: NUCLEOTIDE_MUTATIONS_ENDPOINT,
+                        body: {
+                            pangoLineage: 'JN.1*',
+                            dateFrom: '2024-05-01',
+                            dateTo: '2024-05-31',
+                            minProportion: 0.001,
+                        },
+                        response: {
+                            status: 200,
+                            body: nucleotideMutation_05,
+                        },
+                    },
+                },
+                {
+                    matcher: {
+                        name: 'nucleotideMutations_06',
+                        url: NUCLEOTIDE_MUTATIONS_ENDPOINT,
+                        body: {
+                            pangoLineage: 'JN.1*',
+                            dateFrom: '2024-06-01',
+                            dateTo: '2024-06-30',
+                            minProportion: 0.001,
+                        },
+                        response: {
+                            status: 200,
+                            body: nucleotideMutation_06,
+                        },
+                    },
+                },
+
+                {
+                    matcher: {
+                        name: 'nucleotideMutations_07',
+                        url: NUCLEOTIDE_MUTATIONS_ENDPOINT,
+                        body: {
+                            pangoLineage: 'JN.1*',
+                            dateFrom: '2024-07-01',
+                            dateTo: '2024-07-31',
+                            minProportion: 0.001,
+                        },
+                        response: {
+                            status: 200,
+                            body: nucleotideMutation_07,
+                        },
+                    },
+                },
+            ],
+        },
+    },
+};

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

@@ -0,0 +1,107 @@
+import { customElement, property } from 'lit/decorators.js';
+
+import { MutationsOverTime, type MutationsOverTimeProps } from '../../preact/mutationsOverTime/mutations-over-time';
+import type { Equals, Expect } from '../../utils/typeAssertions';
+import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
+
+/**
+ * ## Context
+ *
+ * This component displays mutations (substitutions and deletions) over time for a dataset selected by a LAPIS filter.
+ * The shown date range is determined by the date field in the LAPIS filter.
+ * If the date field is not set, the date range is determined by all available dates in the dataset.
+ *
+ * ## Views
+ *
+ * ### Grid View
+ *
+ * The grid view shows the proportion for each mutation over date ranges.
+ *
+ */
+@customElement('gs-mutations-over-time')
+export class MutationsOverTimeComponent extends PreactLitAdapterWithGridJsStyles {
+    /**
+     * Required.
+     *
+     * LAPIS filter to select the displayed data.
+     */
+    @property({ type: Object })
+    lapisFilter: Record<string, string | number | null | boolean> = {};
+
+    /**
+     * The type of the sequence for which the mutations should be shown.
+     */
+    @property({ type: String })
+    sequenceType: 'nucleotide' | 'amino acid' = 'nucleotide';
+
+    /**
+     * A list of tabs with views that this component should provide.
+     */
+    @property({ type: Array })
+    views: 'grid'[] = ['grid'];
+
+    /**
+     * 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';
+
+    /**
+     * The granularity of the time axis.
+     */
+    @property({ type: String })
+    granularity: 'day' | 'week' | 'month' | 'year' = 'week';
+
+    /**
+     * Required.
+     *
+     * The LAPIS field that the data should be aggregated by.
+     * The values will be used for the columns of the grid.
+     * Must be a field of type `date` in LAPIS.
+     */
+    @property({ type: String })
+    lapisDateField: string = 'date';
+
+    override render() {
+        return (
+            <MutationsOverTime
+                lapisFilter={this.lapisFilter}
+                sequenceType={this.sequenceType}
+                views={this.views}
+                width={this.width}
+                height={this.height}
+                granularity={this.granularity}
+                lapisDateField={this.lapisDateField}
+            />
+        );
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'gs-mutations-over-time-component': MutationsOverTimeComponent;
+    }
+}
+
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+type LapisFilterMatches = Expect<
+    Equals<typeof MutationsOverTimeComponent.prototype.lapisFilter, MutationsOverTimeProps['lapisFilter']>
+>;
+type SequenceTypeMatches = Expect<
+    Equals<typeof MutationsOverTimeComponent.prototype.sequenceType, MutationsOverTimeProps['sequenceType']>
+>;
+type ViewsMatches = Expect<Equals<typeof MutationsOverTimeComponent.prototype.views, MutationsOverTimeProps['views']>>;
+type GranularityMatches = Expect<
+    Equals<typeof MutationsOverTimeComponent.prototype.granularity, MutationsOverTimeProps['granularity']>
+>;
+/* eslint-enable @typescript-eslint/no-unused-vars, no-unused-vars */

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

@@ -4,3 +4,4 @@ export { PrevalenceOverTimeComponent } from './gs-prevalence-over-time';
 export { RelativeGrowthAdvantageComponent } from './gs-relative-growth-advantage';
 export { AggregateComponent } from './gs-aggregate';
 export { NumberSequencesOverTimeComponent } from './gs-number-sequences-over-time';
+export { MutationsOverTimeComponent } from './gs-mutations-over-time';