@genspectrum/dashboard-components 1.12.0 → 1.13.0

package/src/query/queryQueriesOverTime.spec.ts

@@ -0,0 +1,432 @@
+import { describe, expect, it } from 'vitest';
+
+import { queryQueriesOverTimeData } from './queryQueriesOverTime';
+import { DUMMY_LAPIS_URL, lapisRequestMocks } from '../../vitest.setup';
+
+describe('queryQueriesOverTime', () => {
+    it('should fetch queries over time and build Map2D structure', async () => {
+        const lapisFilter = { field1: 'value1', field2: 'value2' };
+        const dateField = 'dateField';
+
+        // Mock date aggregation call
+        lapisRequestMocks.aggregated(
+            { ...lapisFilter, fields: [dateField] },
+            {
+                data: [
+                    { count: 1, [dateField]: '2023-01-01' },
+                    { count: 2, [dateField]: '2023-01-03' },
+                ],
+            },
+        );
+
+        const dateRanges = [
+            { dateFrom: '2023-01-01', dateTo: '2023-01-01' },
+            { dateFrom: '2023-01-02', dateTo: '2023-01-02' },
+            { dateFrom: '2023-01-03', dateTo: '2023-01-03' },
+        ];
+
+        // Mock queries over time API call
+        lapisRequestMocks.queriesOverTime([
+            {
+                body: {
+                    filters: lapisFilter,
+                    dateRanges,
+                    queries: [
+                        {
+                            displayLabel: 'Query A',
+                            countQuery: 'gene1:123G AND gene2:456T',
+                            coverageQuery: '!gene1:123N AND !gene2:456N',
+                        },
+                        {
+                            displayLabel: 'Query B',
+                            countQuery: 'gene1:789C',
+                            coverageQuery: '!gene1:789N',
+                        },
+                    ],
+                    dateField,
+                },
+                response: {
+                    data: {
+                        queries: ['Query A', 'Query B'],
+                        dateRanges,
+                        data: [
+                            [
+                                { count: 10, coverage: 100 },
+                                { count: 15, coverage: 100 },
+                                { count: 20, coverage: 100 },
+                            ],
+                            [
+                                { count: 5, coverage: 100 },
+                                { count: 8, coverage: 100 },
+                                { count: 12, coverage: 100 },
+                            ],
+                        ],
+                        totalCountsByDateRange: [100, 120, 150],
+                    },
+                },
+            },
+        ]);
+
+        const { queryOverTimeData } = await queryQueriesOverTimeData(
+            lapisFilter,
+            [
+                {
+                    displayLabel: 'Query A',
+                    countQuery: 'gene1:123G AND gene2:456T',
+                    coverageQuery: '!gene1:123N AND !gene2:456N',
+                },
+                {
+                    displayLabel: 'Query B',
+                    countQuery: 'gene1:789C',
+                    coverageQuery: '!gene1:789N',
+                },
+            ],
+            DUMMY_LAPIS_URL,
+            dateField,
+            'day',
+        );
+
+        // Verify Map2D structure
+        const expectedData = [
+            [
+                { type: 'valueWithCoverage', count: 10, coverage: 100, totalCount: 100 },
+                { type: 'valueWithCoverage', count: 15, coverage: 100, totalCount: 120 },
+                { type: 'valueWithCoverage', count: 20, coverage: 100, totalCount: 150 },
+            ],
+            [
+                { type: 'valueWithCoverage', count: 5, coverage: 100, totalCount: 100 },
+                { type: 'valueWithCoverage', count: 8, coverage: 100, totalCount: 120 },
+                { type: 'valueWithCoverage', count: 12, coverage: 100, totalCount: 150 },
+            ],
+        ];
+
+        // Convert Map2DContents to array for comparison
+        const actualData = Array.from(queryOverTimeData.keysFirstAxis.values()).map((query) => {
+            return Array.from(queryOverTimeData.keysSecondAxis.keys()).map((dateKey) => {
+                return queryOverTimeData.data.get(query)?.get(dateKey);
+            });
+        });
+
+        expect(actualData).to.deep.equal(expectedData);
+
+        // Verify first axis keys (queries)
+        const queries = Array.from(queryOverTimeData.keysFirstAxis.values());
+        expect(queries).to.deep.equal(['Query A', 'Query B']);
+
+        // Verify second axis keys (dates)
+        const dates = Array.from(queryOverTimeData.keysSecondAxis.values());
+        expect(dates[0].dateString).toBe('2023-01-01');
+        expect(dates[1].dateString).toBe('2023-01-02');
+        expect(dates[2].dateString).toBe('2023-01-03');
+    });
+
+    it('should handle dates with no data (totalCount = 0)', async () => {
+        const lapisFilter = { field1: 'value1' };
+        const dateField = 'dateField';
+
+        lapisRequestMocks.aggregated(
+            { ...lapisFilter, fields: [dateField] },
+            {
+                data: [
+                    { count: 1, [dateField]: '2023-01-01' },
+                    { count: 1, [dateField]: '2023-01-03' },
+                ],
+            },
+        );
+
+        const dateRanges = [
+            { dateFrom: '2023-01-01', dateTo: '2023-01-01' },
+            { dateFrom: '2023-01-02', dateTo: '2023-01-02' },
+            { dateFrom: '2023-01-03', dateTo: '2023-01-03' },
+        ];
+
+        lapisRequestMocks.queriesOverTime([
+            {
+                body: {
+                    filters: lapisFilter,
+                    dateRanges,
+                    queries: [
+                        {
+                            displayLabel: 'Test Query',
+                            countQuery: 'gene1:123G',
+                            coverageQuery: '!gene1:123N',
+                        },
+                    ],
+                    dateField,
+                },
+                response: {
+                    data: {
+                        queries: ['Test Query'],
+                        dateRanges,
+                        data: [
+                            [
+                                { count: 5, coverage: 50 },
+                                { count: 0, coverage: 0 },
+                                { count: 8, coverage: 60 },
+                            ],
+                        ],
+                        totalCountsByDateRange: [50, 0, 60],
+                    },
+                },
+            },
+        ]);
+
+        const { queryOverTimeData } = await queryQueriesOverTimeData(
+            lapisFilter,
+            [
+                {
+                    displayLabel: 'Test Query',
+                    countQuery: 'gene1:123G',
+                    coverageQuery: '!gene1:123N',
+                },
+            ],
+            DUMMY_LAPIS_URL,
+            dateField,
+            'day',
+        );
+
+        const actualData = Array.from(queryOverTimeData.keysFirstAxis.values()).map((query) => {
+            return Array.from(queryOverTimeData.keysSecondAxis.keys()).map((dateKey) => {
+                return queryOverTimeData.data.get(query)?.get(dateKey);
+            });
+        });
+
+        // Middle date should be null (no data)
+        expect(actualData).to.deep.equal([
+            [
+                { type: 'valueWithCoverage', count: 5, coverage: 50, totalCount: 50 },
+                null,
+                { type: 'valueWithCoverage', count: 8, coverage: 60, totalCount: 60 },
+            ],
+        ]);
+    });
+
+    it('should handle zero coverage (belowThreshold)', async () => {
+        const lapisFilter = { field1: 'value1' };
+        const dateField = 'dateField';
+
+        lapisRequestMocks.aggregated(
+            { ...lapisFilter, fields: [dateField] },
+            {
+                data: [{ count: 1, [dateField]: '2023-01-01' }],
+            },
+        );
+
+        const dateRanges = [{ dateFrom: '2023-01-01', dateTo: '2023-01-01' }];
+
+        lapisRequestMocks.queriesOverTime([
+            {
+                body: {
+                    filters: lapisFilter,
+                    dateRanges,
+                    queries: [
+                        {
+                            displayLabel: 'Zero Coverage Query',
+                            countQuery: 'gene1:123G',
+                            coverageQuery: '!gene1:123N',
+                        },
+                    ],
+                    dateField,
+                },
+                response: {
+                    data: {
+                        queries: ['Zero Coverage Query'],
+                        dateRanges,
+                        data: [[{ count: 0, coverage: 0 }]],
+                        totalCountsByDateRange: [100],
+                    },
+                },
+            },
+        ]);
+
+        const { queryOverTimeData } = await queryQueriesOverTimeData(
+            lapisFilter,
+            [
+                {
+                    displayLabel: 'Zero Coverage Query',
+                    countQuery: 'gene1:123G',
+                    coverageQuery: '!gene1:123N',
+                },
+            ],
+            DUMMY_LAPIS_URL,
+            dateField,
+            'day',
+        );
+
+        const actualData = Array.from(queryOverTimeData.keysFirstAxis.values()).map((query) => {
+            return Array.from(queryOverTimeData.keysSecondAxis.keys()).map((dateKey) => {
+                return queryOverTimeData.data.get(query)?.get(dateKey);
+            });
+        });
+
+        expect(actualData).to.deep.equal([[{ type: 'belowThreshold', totalCount: 100 }]]);
+    });
+
+    it('should return empty structure when no dates are available', async () => {
+        const lapisFilter = { field1: 'value1' };
+        const dateField = 'dateField';
+
+        lapisRequestMocks.aggregated(
+            { ...lapisFilter, fields: [dateField] },
+            {
+                data: [],
+            },
+        );
+
+        const { queryOverTimeData } = await queryQueriesOverTimeData(
+            lapisFilter,
+            [
+                {
+                    displayLabel: 'Test Query',
+                    countQuery: 'gene1:123G',
+                    coverageQuery: '!gene1:123N',
+                },
+            ],
+            DUMMY_LAPIS_URL,
+            dateField,
+            'day',
+        );
+
+        expect(Array.from(queryOverTimeData.keysFirstAxis.values())).to.deep.equal([]);
+        expect(Array.from(queryOverTimeData.keysSecondAxis.values())).to.deep.equal([]);
+        expect(queryOverTimeData.data.size).toBe(0);
+    });
+
+    it('should respect dateFrom filter', async () => {
+        const dateField = 'dateField';
+        const lapisFilter = { field1: 'value1', [`${dateField}From`]: '2023-01-02' };
+
+        lapisRequestMocks.aggregated(
+            { ...lapisFilter, fields: [dateField] },
+            {
+                data: [
+                    { count: 1, [dateField]: '2023-01-02' },
+                    { count: 1, [dateField]: '2023-01-03' },
+                ],
+            },
+        );
+
+        const dateRanges = [
+            { dateFrom: '2023-01-02', dateTo: '2023-01-02' },
+            { dateFrom: '2023-01-03', dateTo: '2023-01-03' },
+        ];
+
+        lapisRequestMocks.queriesOverTime([
+            {
+                body: {
+                    filters: lapisFilter,
+                    dateRanges,
+                    queries: [
+                        {
+                            displayLabel: 'Test',
+                            countQuery: 'gene1:123G',
+                            coverageQuery: '!gene1:123N',
+                        },
+                    ],
+                    dateField,
+                },
+                response: {
+                    data: {
+                        queries: ['Test'],
+                        dateRanges,
+                        data: [
+                            [
+                                { count: 5, coverage: 50 },
+                                { count: 8, coverage: 60 },
+                            ],
+                        ],
+                        totalCountsByDateRange: [50, 60],
+                    },
+                },
+            },
+        ]);
+
+        const { queryOverTimeData } = await queryQueriesOverTimeData(
+            lapisFilter,
+            [
+                {
+                    displayLabel: 'Test',
+                    countQuery: 'gene1:123G',
+                    coverageQuery: '!gene1:123N',
+                },
+            ],
+            DUMMY_LAPIS_URL,
+            dateField,
+            'day',
+        );
+
+        const dates = Array.from(queryOverTimeData.keysSecondAxis.values());
+        expect(dates.length).toBe(2);
+        expect(dates[0].dateString).toBe('2023-01-02');
+        expect(dates[1].dateString).toBe('2023-01-03');
+    });
+
+    it('should work with different granularities', async () => {
+        const lapisFilter = { field1: 'value1' };
+        const dateField = 'dateField';
+
+        lapisRequestMocks.aggregated(
+            { ...lapisFilter, fields: [dateField] },
+            {
+                data: [
+                    { count: 1, [dateField]: '2023-01-15' },
+                    { count: 1, [dateField]: '2023-02-20' },
+                ],
+            },
+        );
+
+        const dateRanges = [
+            { dateFrom: '2023-01-01', dateTo: '2023-01-31' },
+            { dateFrom: '2023-02-01', dateTo: '2023-02-28' },
+        ];
+
+        lapisRequestMocks.queriesOverTime([
+            {
+                body: {
+                    filters: lapisFilter,
+                    dateRanges,
+                    queries: [
+                        {
+                            displayLabel: 'Monthly Query',
+                            countQuery: 'gene1:123G',
+                            coverageQuery: '!gene1:123N',
+                        },
+                    ],
+                    dateField,
+                },
+                response: {
+                    data: {
+                        queries: ['Monthly Query'],
+                        dateRanges,
+                        data: [
+                            [
+                                { count: 10, coverage: 100 },
+                                { count: 20, coverage: 150 },
+                            ],
+                        ],
+                        totalCountsByDateRange: [100, 150],
+                    },
+                },
+            },
+        ]);
+
+        const { queryOverTimeData } = await queryQueriesOverTimeData(
+            lapisFilter,
+            [
+                {
+                    displayLabel: 'Monthly Query',
+                    countQuery: 'gene1:123G',
+                    coverageQuery: '!gene1:123N',
+                },
+            ],
+            DUMMY_LAPIS_URL,
+            dateField,
+            'month',
+        );
+
+        const dates = Array.from(queryOverTimeData.keysSecondAxis.values());
+        expect(dates.length).toBe(2);
+        expect(dates[0].dateString).toBe('2023-01');
+        expect(dates[1].dateString).toBe('2023-02');
+    });
+});

package/src/query/queryQueriesOverTime.ts

@@ -0,0 +1,125 @@
+import { queryDatesInDataset } from './queryDatesInDataset';
+import { fetchQueriesOverTime } from '../lapisApi/lapisApi';
+import { type QueryDefinition } from '../lapisApi/lapisTypes';
+import { UserFacingError } from '../preact/components/error-display';
+import { type LapisFilter, type TemporalGranularity } from '../types';
+import { type ProportionValue } from './queryMutationsOverTime';
+import { type Map2DContents } from '../utils/map2d';
+import { type Temporal } from '../utils/temporalClass';
+
+const MAX_NUMBER_OF_GRID_COLUMNS = 200;
+
+/**
+ * Query data for multiple queries over time periods.
+ *
+ * @param lapisFilter - Standard LAPIS filters to apply
+ * @param queries - Array of query definitions with countQuery and coverageQuery
+ * @param lapis - LAPIS URL
+ * @param lapisDateField - The metadata field to use for dates (e.g., "date", "submissionDate")
+ * @param granularity - Temporal granularity (day, week, month, year)
+ * @param signal - Optional abort signal for cancellation
+ * @returns Map2D structure with queries as first axis, dates as second axis
+ */
+export async function queryQueriesOverTimeData(
+    lapisFilter: LapisFilter,
+    queries: QueryDefinition[],
+    lapis: string,
+    lapisDateField: string,
+    granularity: TemporalGranularity,
+    signal?: AbortSignal,
+) {
+    const requestedDateRanges = await queryDatesInDataset(lapisFilter, lapis, granularity, lapisDateField, signal);
+
+    if (requestedDateRanges.length > MAX_NUMBER_OF_GRID_COLUMNS) {
+        throw new UserFacingError(
+            'Too many dates',
+            `The dataset would contain ${requestedDateRanges.length} date intervals. ` +
+                `Please reduce the number to below ${MAX_NUMBER_OF_GRID_COLUMNS} to display the data. ` +
+                'You can achieve this by either narrowing the date range in the provided LAPIS filter or by selecting a larger granularity.',
+        );
+    }
+
+    if (requestedDateRanges.length === 0) {
+        return {
+            queryOverTimeData: {
+                keysFirstAxis: new Map<string, string>(),
+                keysSecondAxis: new Map<string, Temporal>(),
+                data: new Map<string, Map<string, ProportionValue>>(),
+            } as Map2DContents<string, Temporal, ProportionValue>,
+        };
+    }
+
+    const apiResult = await fetchQueriesOverTime(
+        lapis,
+        {
+            filters: lapisFilter,
+            queries: queries.map((q) => ({
+                displayLabel: q.displayLabel,
+                countQuery: q.countQuery,
+                coverageQuery: q.coverageQuery,
+            })),
+            dateRanges: requestedDateRanges.map((date) => ({
+                dateFrom: date.firstDay.toString(),
+                dateTo: date.lastDay.toString(),
+            })),
+            dateField: lapisDateField,
+        },
+        signal,
+    );
+
+    const totalCounts = apiResult.data.totalCountsByDateRange;
+    const responseQueries = apiResult.data.queries;
+
+    const queryOverTimeData: Map2DContents<string, Temporal, ProportionValue> = {
+        keysFirstAxis: new Map(responseQueries.map((query) => [query, query])),
+        keysSecondAxis: new Map(requestedDateRanges.map((date) => [date.dateString, date])),
+        data: new Map(
+            responseQueries.map((query, i) => [
+                query,
+                new Map(
+                    requestedDateRanges.map((date, j): [string, ProportionValue] => {
+                        if (totalCounts[j] === 0) {
+                            return [date.dateString, null];
+                        }
+
+                        const count = apiResult.data.data[i][j].count;
+                        const coverage = apiResult.data.data[i][j].coverage;
+                        const totalCount = totalCounts[j];
+
+                        if (coverage === 0) {
+                            return [
+                                date.dateString,
+                                {
+                                    type: 'belowThreshold',
+                                    totalCount,
+                                },
+                            ];
+                        }
+
+                        return [
+                            date.dateString,
+                            {
+                                type: 'valueWithCoverage',
+                                count,
+                                coverage,
+                                totalCount,
+                            },
+                        ];
+                    }),
+                ),
+            ]),
+        ),
+    };
+
+    return {
+        queryOverTimeData,
+    };
+}
+
+export function serializeQuery(displayLabel: string): string {
+    return displayLabel;
+}
+
+export function serializeTemporal(date: Temporal): string {
+    return date.dateString;
+}

package/src/utilEntrypoint.ts

@@ -51,4 +51,6 @@ export {
 } from './preact/numberRangeFilter/NumberRangeFilterChangedEvent';
 
 export { type MeanProportionInterval } from './preact/mutationsOverTime/mutations-over-time';
-export { type CustomColumn } from './preact/mutationsOverTime/mutations-over-time-grid';
+export { type CustomColumn } from './preact/components/features-over-time-grid';
+
+export { type QueryDefinition } from './lapisApi/lapisTypes';

package/src/utils/mutations.spec.ts

@@ -34,6 +34,12 @@ describe('SubstitutionClass', () => {
             expect(substitution.toString()).to.equal(expected);
         }
     });
+
+    it('should parse X correclty', () => {
+        expect(SubstitutionClass.parse('NP:X114D')).deep.equal(new SubstitutionClass('NP', 'X', 'D', 114));
+        expect(SubstitutionClass.parse('NP:D114X')).deep.equal(new SubstitutionClass('NP', 'D', 'X', 114));
+        expect(SubstitutionClass.parse('NP:X114X')).deep.equal(new SubstitutionClass('NP', 'X', 'X', 114));
+    });
 });
 
 describe('DeletionClass', () => {

package/src/utils/mutations.ts

@@ -15,7 +15,7 @@ export interface MutationClass extends Mutation {
 
 // Allowed IUPAC characters: https://www.bioinformatics.org/sms/iupac.html
 const nucleotideChars = 'ACGTRYKMSWBDHVN';
-const aminoAcidChars = 'ACDEFGHIKLMNPQRSTVWY';
+const aminoAcidChars = 'ACDEFGHIKLMNPQRSTVWYX';
 
 function segmentPart(isOptional: boolean) {
     const segmentPart = `(?<segment>[A-Z0-9_-]+):`;

package/src/utils/temporalClass.ts

@@ -501,6 +501,10 @@ export function addUnit(temporal: TemporalClass, amount: number): TemporalClass
     throw new Error(`Invalid argument: ${temporal}`);
 }
 
+/**
+ * Given a date like 2025-10-15 and a granularity ("day", "week", ...), returns a date range
+ * like "2025-10-15" (day) or "2025-W42" (week) etc.
+ */
 export function parseDateStringToTemporal(date: string, granularity: TemporalGranularity) {
     const cache = TemporalCache.getInstance();
     const day = cache.getYearMonthDay(date);

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

@@ -32,9 +32,6 @@ describe('gs-mutations-over-time', () => {
         expectTypeOf<typeof MutationsOverTimeComponent.prototype.initialMeanProportionInterval>().toEqualTypeOf<
             MutationsOverTimeProps['initialMeanProportionInterval']
         >();
-        expectTypeOf<typeof MutationsOverTimeComponent.prototype.useNewEndpoint>().toEqualTypeOf<
-            MutationsOverTimeProps['useNewEndpoint']
-        >();
         expectTypeOf<typeof MutationsOverTimeComponent.prototype.pageSizes>().toEqualTypeOf<
             MutationsOverTimeProps['pageSizes']
         >();