@genspectrum/dashboard-components 0.1.4 → 0.1.5

package/src/web-components/display/prevalence-over-time-component.tsx

@@ -3,27 +3,102 @@ import { customElement, property } from 'lit/decorators.js';
 import PrevalenceOverTime, { type View } from '../../preact/prevalenceOverTime/prevalence-over-time';
 import { type ConfidenceIntervalMethod } from '../../preact/shared/charts/confideceInterval';
 import { type NamedLapisFilter, type TemporalGranularity } from '../../types';
+import { type Equals, type Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
 
+/**
+ * This component displays the prevalence over time of one or more variants.
+ * The prevalence is calculated as the ratio of the number of cases of each variant given as `numerator`
+ * to the number of cases of the variant given as `denominator`.
+ *
+ * In the chart views,
+ * - the user can select whether to display a confidence interval (not available in the bubble chart).
+ *   The confidence interval is calculated using [Wilson score interval](https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval),
+ *   with a confidence level of 95%.
+ * - the x-axis shows time steps in the selected `granularity`.
+ * - the user can select the y-axis scale (linear, logistic, logit).
+ *
+ * ## Views
+ *
+ * ### Bar View
+ *
+ * Displays the prevalence over time as a bar chart.
+ * Shows a bar for each variant in the `numerator` on every time step.
+ *
+ * ### Line View
+ *
+ * Displays the prevalence over time as a line chart.
+ * Each data point is connected for better visibility.
+ * Shows a line for each variant in the `numerator`.
+ *
+ * ### Bubble View
+ *
+ * Displays the prevalence over time as a bubble chart.
+ * The size of the bubbles represents the number of cases of the `denominator` variant.
+ * The height of the bubbles represents the prevalence of the `numerator` variants.
+ *
+ * ### Table View
+ *
+ * Displays the prevalence over time as a table with one row per time point.
+ */
 @customElement('gs-prevalence-over-time')
 export class PrevalenceOverTimeComponent extends PreactLitAdapterWithGridJsStyles {
+    /**
+     * Either a single variant or an array of variants to compare.
+     * This must be a valid LAPIS filter object with an additional `displayName` property
+     * which will be used as the label for the variant in the views,
+     * or an array of such objects.
+     */
     @property({ type: Object })
-    numerator: NamedLapisFilter | NamedLapisFilter[] = { displayName: '' };
+    numerator:
+        | (Record<string, string | number | null | boolean> & { displayName: string })
+        | (Record<string, string | number | null | boolean> & {
+              displayName: string;
+          })[] = { displayName: '' };
 
+    /**
+     * The variant that the variants in `numerator` are compared to.
+     */
     @property({ type: Object })
-    denominator: NamedLapisFilter = { displayName: '' };
+    denominator: Record<string, string | number | null | boolean> & { displayName: string } = { displayName: '' };
 
+    /**
+     * The granularity of the time axis.
+     */
     @property({ type: String })
-    granularity: TemporalGranularity = 'day';
+    granularity: 'day' | 'week' | 'month' | 'year' = 'day';
 
+    /**
+     * The number of time steps to use for smoothing the data.
+     * `0` means no smoothing.
+     * Must be a non-negative integer.
+     *
+     * For a given time, the shown value is the mean of the neighbouring measured values.
+     * The `smoothingWindow` value provides the number of neighbouring values to take into account.
+     * The resulting time is computed via `Math.floor(smoothingWindow / 2)`.
+     */
     @property({ type: Number })
     smoothingWindow: number = 0;
 
+    /**
+     * A list of tabs with views that this component should provide.
+     */
     @property({ type: Array })
-    views: View[] = ['bar', 'line', 'bubble', 'table'];
+    views: ('bar' | 'line' | 'bubble' | 'table')[] = ['bar', 'line', 'bubble', 'table'];
 
+    /**
+     * A list of methods to calculate the confidence interval.
+     * The option `none` is always available and disables confidence intervals.
+     * Pass an empty array to disable the confidence interval selector.
+     */
     @property({ type: Array })
-    confidenceIntervalMethods: ConfidenceIntervalMethod[] = ['wilson'];
+    confidenceIntervalMethods: ('wilson' | 'none')[] = ['wilson'];
+
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    @property({ type: String })
+    headline: string | undefined = 'Prevalence over time';
 
     /**
      * The size of the component.
@@ -46,6 +121,7 @@ export class PrevalenceOverTimeComponent extends PreactLitAdapterWithGridJsStyle
                 views={this.views}
                 confidenceIntervalMethods={this.confidenceIntervalMethods}
                 size={this.size}
+                headline={this.headline}
             />
         );
     }
@@ -56,3 +132,15 @@ declare global {
         'gs-prevalence-over-time': PrevalenceOverTimeComponent;
     }
 }
+
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+type NumeratorMatches = Expect<
+    Equals<typeof PrevalenceOverTimeComponent.prototype.numerator, NamedLapisFilter | NamedLapisFilter[]>
+>;
+type DenominatorMatches = Expect<Equals<typeof PrevalenceOverTimeComponent.prototype.denominator, NamedLapisFilter>>;
+type GranularityMatches = Expect<Equals<typeof PrevalenceOverTimeComponent.prototype.granularity, TemporalGranularity>>;
+type ViewsMatches = Expect<Equals<typeof PrevalenceOverTimeComponent.prototype.views, View[]>>;
+type ConfidenceIntervalMethodsMatches = Expect<
+    Equals<typeof PrevalenceOverTimeComponent.prototype.confidenceIntervalMethods, ConfidenceIntervalMethod[]>
+>;
+/* eslint-enable @typescript-eslint/no-unused-vars, no-unused-vars */

package/src/web-components/display/relative-growth-advantage-component.stories.ts

@@ -3,11 +3,20 @@ import { html } from 'lit';
 
 import './relative-growth-advantage-component';
 import '../app';
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { AGGREGATED_ENDPOINT, LAPIS_URL } from '../../constants';
 import denominator from '../../preact/relativeGrowthAdvantage/__mockData__/denominator.json';
 import numerator from '../../preact/relativeGrowthAdvantage/__mockData__/numerator.json';
 import { type RelativeGrowthAdvantageProps } from '../../preact/relativeGrowthAdvantage/relative-growth-advantage';
 
+const codeExample = String.raw`
+<gs-relative-growth-advantage
+    numerator='{ "country": "Switzerland", "pangoLineage": "B.1.1.7", "dateFrom": "2020-12-01" }'
+    denominator='{ "country": "Switzerland", "dateFrom": "2020-12-01" }'
+    generationTime="7"
+    views='["line"]'
+></gs-relative-growth-advantage>`;
+
 const meta: Meta<RelativeGrowthAdvantageProps> = {
     title: 'Visualization/Relative growth advantage',
     component: 'gs-relative-growth-advantage',
@@ -20,7 +29,17 @@ const meta: Meta<RelativeGrowthAdvantageProps> = {
             control: { type: 'check' },
         },
         size: [{ control: 'object' }],
+        headline: { control: 'text' },
     },
+    parameters: withComponentDocs({
+        componentDocs: {
+            tag: 'gs-relative-growth-advantage',
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
+    tags: ['autodocs'],
 };
 
 export default meta;
@@ -34,6 +53,7 @@ const Template: StoryObj<RelativeGrowthAdvantageProps> = {
                 .generationTime=${args.generationTime}
                 .views=${args.views}
                 .size=${args.size}
+                .headline=${args.headline}
             ></gs-relative-growth-advantage>
         </gs-app>
     `,
@@ -47,6 +67,7 @@ export const Default: StoryObj<RelativeGrowthAdvantageProps> = {
         generationTime: 7,
         views: ['line'],
         size: { width: '100%', height: '700px' },
+        headline: 'Relative growth advantage',
     },
     parameters: {
         fetchMock: {

package/src/web-components/display/relative-growth-advantage-component.tsx

@@ -2,21 +2,65 @@ import { customElement, property } from 'lit/decorators.js';
 
 import { RelativeGrowthAdvantage, type View } from '../../preact/relativeGrowthAdvantage/relative-growth-advantage';
 import type { LapisFilter } from '../../types';
+import { type Equals, type Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapter } from '../PreactLitAdapter';
 
+/**
+ * We assume a discrete time model, where new infections happen exactly every `generationTime` days.
+ * This is what we call a "generation".
+ *
+ * This component estimates the relative growth advantage of a variant by performing a logistic regression.
+ * Based on the inferred logistic growth rate, we derive the relative growth advantage (per generation).
+ *
+ * For details on the scientific method, see:
+ * Chen, Chaoran, et al. "Quantification of the spread of SARS-CoV-2 variant B.1.1.7 in Switzerland." Epidemics (2021);
+ * doi: [10.1016/j.epidem.2021.100480](https://doi.org/10.1016/j.epidem.2021.100480)
+ *
+ * This component fetches aggregated data from LAPIS.
+ * Then the data is sent to `https://cov-spectrum.org/api/v2/computed/model/chen2021Fitness`
+ * which performs the logistic regression and calculates the relative growth advantage.
+ *
+ * ## Views
+ *
+ * ### Line View
+ *
+ * The line view shows the relative growth advantage over time in a line chart.
+ * The dots in the plot show the proportions of the focal variant (`numerator`) to the `denominator` variant
+ * for every day as observed in the data.
+ * The line shows a logistic curve fitted to the data points, including a 95% confidence interval.
+ */
 @customElement('gs-relative-growth-advantage')
 export class RelativeGrowthAdvantageComponent extends PreactLitAdapter {
+    /**
+     * The LAPIS filter for the focal variant.
+     */
     @property({ type: Object })
-    numerator: LapisFilter = {};
+    numerator: Record<string, string | number | null | boolean> = {};
 
+    /**
+     * The LAPIS filter for the variant that the focal variant (`numerator`) should be compared to.
+     */
     @property({ type: Object })
-    denominator: LapisFilter = {};
+    denominator: Record<string, string | number | null | boolean> = {};
 
+    /**
+     * The generation time represents the number of days over which the variant's relative growth advantage is measured.
+     * For example, if we set a generation time of 7 days, then we estimate the growth advantage per week.
+     */
     @property({ type: Number })
     generationTime: number = 7;
 
+    /**
+     * A list of tabs with views that this component should provide.
+     */
     @property({ type: Array })
-    views: View[] = ['line'];
+    views: 'line'[] = ['line'];
+
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    @property({ type: String })
+    headline: string | undefined = 'Relative growth advantage';
 
     /**
      * The size of the component.
@@ -37,6 +81,7 @@ export class RelativeGrowthAdvantageComponent extends PreactLitAdapter {
                 generationTime={this.generationTime}
                 views={this.views}
                 size={this.size}
+                headline={this.headline}
             />
         );
     }
@@ -47,3 +92,9 @@ declare global {
         'gs-relative-growth-advantage': RelativeGrowthAdvantageComponent;
     }
 }
+
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+type NumeratorMatches = Expect<Equals<typeof RelativeGrowthAdvantageComponent.prototype.numerator, LapisFilter>>;
+type DenominatorMatches = Expect<Equals<typeof RelativeGrowthAdvantageComponent.prototype.denominator, LapisFilter>>;
+type ViewsMatches = Expect<Equals<typeof RelativeGrowthAdvantageComponent.prototype.views, View[]>>;
+/* eslint-enable @typescript-eslint/no-unused-vars, no-unused-vars */

package/src/web-components/input/date-range-selector-component.stories.ts

@@ -3,6 +3,7 @@ import { expect, waitFor } from '@storybook/test';
 import type { Meta, StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { LAPIS_URL } from '../../constants';
 import {
     type DateRangeSelectorProps,
@@ -19,15 +20,28 @@ import '../app';
 import { toYYYYMMDD } from '../../preact/dateRangeSelector/dateConversion';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 
+const codeExample = String.raw`
+<gs-date-range-selector
+    customSelectOptions='[{ "label": "Year 2021", "dateFrom": "2021-01-01", "dateTo": "2021-12-31" }]'
+    earliestDate="1970-01-01"
+    initialValue="${PRESET_VALUE_LAST_6_MONTHS}"
+></gs-date-range-selector>`;
+
 const meta: Meta<DateRangeSelectorProps<'CustomDateRange'>> = {
     title: 'Input/DateRangeSelector',
     component: 'gs-date-range-selector',
-    parameters: {
+    parameters: withComponentDocs({
         actions: {
             handles: ['gs-date-range-changed'],
         },
         fetchMock: {},
-    },
+        componentDocs: {
+            tag: 'gs-date-range-selector',
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
     argTypes: {
         initialValue: {
             control: {
@@ -51,6 +65,7 @@ const meta: Meta<DateRangeSelectorProps<'CustomDateRange'>> = {
         initialValue: PRESET_VALUE_LAST_6_MONTHS,
     },
     decorators: [withActions],
+    tags: ['autodocs'],
 };
 
 export default meta;

package/src/web-components/input/date-range-selector-component.tsx

@@ -5,21 +5,64 @@ import {
     DateRangeSelector,
     type PresetOptionValues,
 } from '../../preact/dateRangeSelector/date-range-selector';
+import { type Equals, type Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapter } from '../PreactLitAdapter';
 
 /**
- * @fires {CustomEvent<{ dateFrom: string; dateTo: string; }>} gs-date-range-changed - When the date range has changed
+ * ## Context
+ * This component is a group of input fields designed to specify a date range. It consists of 3 fields:
+ *
+ * - a select field to choose a predefined date range,
+ * - an input field with an attached date picker for the start date,
+ * - an input field with an attached date picker for the end date.
+ *
+ * Setting a value in the select field will overwrite the previous values of the start and end date.
+ * Setting a value in either of the date pickers will set the select field to "custom",
+ * which represents an arbitrary date range.
+ *
+ * @fires {CustomEvent<{ dateFrom: string; dateTo: string; }>} gs-date-range-changed
+ * Fired when:
+ * - The select field is changed,
+ * - A date is selected in either of the date pickers,
+ * - A date was typed into either of the date input fields, and the input field loses focus ("on blur").
+ * Contains the dates in the format `YYYY-MM-DD`.
  */
 @customElement('gs-date-range-selector')
-export class DateRangeSelectorComponent<CustomLabel extends string> extends PreactLitAdapter {
+export class DateRangeSelectorComponent extends PreactLitAdapter {
+    /**
+     * An array of custom options that the select field should provide,
+     * in addition to the predefined options.
+     * The `label` will be shown to the user, and it will be available as `initialValue`.
+     * The dates must be in the format `YYYY-MM-DD`.
+     */
     @property({ type: Array })
-    customSelectOptions: CustomSelectOption<CustomLabel>[] = [];
+    customSelectOptions: { label: string; dateFrom: string; dateTo: string }[] = [];
 
+    /**
+     * The `dateFrom` value to use in the `allTimes` preset in the format `YYYY-MM-DD`.
+     */
     @property({ type: String })
     earliestDate: string | undefined = '1900-01-01';
 
+    // prettier-ignore
+    // The multiline union type must not start with `| 'custom'` - Storybook will list "" as the first type which is wrong
+    /**
+     * The initial value to use for this date range selector.
+     * Must be a valid label from the preset labels or a `label` given in the `customSelectOptions`.
+     *
+     * If the value is invalid, the component will default to `'last6Months'`.
+     */
     @property()
-    initialValue: PresetOptionValues | CustomLabel | string | undefined = '';
+    initialValue:
+        'custom'
+        | 'allTimes'
+        | 'last2Weeks'
+        | 'lastMonth'
+        | 'last2Months'
+        | 'last3Months'
+        | 'last6Months'
+        | string
+        | undefined = 'last6Months';
 
     override render() {
         return (
@@ -34,7 +77,7 @@ export class DateRangeSelectorComponent<CustomLabel extends string> extends Prea
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-date-range-selector': DateRangeSelectorComponent<string>;
+        'gs-date-range-selector': DateRangeSelectorComponent;
     }
 
     interface HTMLElementEventMap {
@@ -44,3 +87,12 @@ declare global {
         }>;
     }
 }
+
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+type CustomSelectOptionsMatches = Expect<
+    Equals<typeof DateRangeSelectorComponent.prototype.customSelectOptions, CustomSelectOption<string>[]>
+>;
+type InitialValueMatches = Expect<
+    Equals<typeof DateRangeSelectorComponent.prototype.initialValue, PresetOptionValues | string | undefined>
+>;
+/* eslint-enable @typescript-eslint/no-unused-vars, no-unused-vars */

package/src/web-components/input/mutation-filter-component.stories.ts

@@ -3,22 +3,32 @@ import { expect, fn, userEvent, waitFor } from '@storybook/test';
 import type { Meta, StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { LAPIS_URL } from '../../constants';
 import '../app';
 import { type MutationFilterProps } from '../../preact/mutationFilter/mutation-filter';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 import './mutation-filter-component';
 
-const meta: Meta = {
+const codeExample = String.raw`<gs-mutation-filter initialValue='["A123T"]'></gs-mutation-filter>`;
+
+const meta: Meta<MutationFilterProps> = {
     title: 'Input/Mutation filter',
     component: 'gs-mutation-filter',
-    parameters: {
+    parameters: withComponentDocs({
         actions: {
             handles: ['gs-mutation-filter-changed', 'gs-mutation-filter-on-blur'],
         },
         fetchMock: {},
-    },
+        componentDocs: {
+            tag: 'gs-mutation-filter',
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
     decorators: [withActions],
+    tags: ['autodocs'],
 };
 
 export default meta;

package/src/web-components/input/mutation-filter-component.tsx

@@ -6,11 +6,59 @@ import { MutationFilter, type SelectedMutationFilterStrings } from '../../preact
 import { PreactLitAdapter } from '../PreactLitAdapter';
 
 /**
- * @fires {CustomEvent<SelectedMutationFilterStrings>} gs-mutation-filter-changed - When the mutation filter values have changed
- * @fires {CustomEvent<SelectedMutationFilterStrings>} gs-mutation-filter-on-blur - When the mutation filter has lost focus
+ * ## Context
+ * This component provides an input field to specify filters for nucleotide and amino acid mutations and insertions.
+ *
+ * Input values have to be provided one at a time and submitted by pressing the Enter key or by clicking the '+' button.
+ * After submission, the component validates the input and fires an event with the selected mutations.
+ * All previously selected mutations are displayed at the input field and added to the event.
+ * Users can remove a mutation by clicking the 'x' button next to the mutation.
+ *
+ * Validation of the input is performed according to the following rules:
+ *
+ * Mutations have to conform to the following format: `<gene/segment>:<symbol at reference><position><Substituted symbol/Deletion>`
+ *     - Gene/segment: The gene or segment where the mutation occurs. Must be contained in the reference genome
+ *       (Optional for elements with only one gene/segment)
+ *     - Symbol at reference: The symbol at the reference position. (Optional)
+ *     - Position: The position of the mutation. (Required)
+ *     - Substituted symbol/Deletion: The substituted symbol or '-' for a deletion. (Required)
+ *     Example: S:614G, 614G, 614- or 614G
+ *
+ * Insertions have to conform to the following format: `ins_<gene/segment>:<position>:<Inserted symbols>`
+ *     - Gene/segment: The gene or segment where the insertion occurs. Must be contained in the reference genome
+ *       (Optional for elements with only one gene/segment)
+ *     - Position: The position of the insertion. (Required)
+ *     - Inserted symbols: The symbols that are inserted. (Required)
+ *     Example: ins_S:614:G, ins_614:G
+ *
+ * @fires {CustomEvent<{
+ *      nucleotideMutations: string[],
+ *      aminoAcidMutations: string[],
+ *      nucleotideInsertions: string[],
+ *      aminoAcidInsertions: string[]
+ *  }>} gs-mutation-filter-changed
+ * Fired when:
+ * - The user has submitted a valid mutation or insertion
+ * - The user has removed a mutation or insertion
+ *
+ * @fires {CustomEvent<{
+ *      nucleotideMutations: string[],
+ *      aminoAcidMutations: string[],
+ *      nucleotideInsertions: string[],
+ *      aminoAcidInsertions: string[]
+ *  }>} gs-mutation-filter-on-blur
+ * Fired when:
+ * - the mutation filter has lost focus
+ * Contains the selected mutations in the format
  */
 @customElement('gs-mutation-filter')
 export class MutationFilterComponent extends PreactLitAdapter {
+    /**
+     * The initial value to use for this mutation filter.
+     * Must be either
+     * - an array of strings of valid mutations.
+     * - an object with the keys `nucleotideMutations`, `aminoAcidMutations`, `nucleotideInsertions` and `aminoAcidInsertions` and corresponding string arrays.
+     */
     @property()
     initialValue: SelectedMutationFilterStrings | string[] | undefined = undefined;
 

package/src/web-components/input/text-input-component.stories.ts

@@ -3,6 +3,7 @@ import { expect, fn, userEvent, waitFor } from '@storybook/test';
 import type { Meta, StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { AGGREGATED_ENDPOINT, LAPIS_URL } from '../../constants';
 import '../app';
 import './text-input-component';
@@ -10,10 +11,13 @@ import data from '../../preact/textInput/__mockData__/aggregated_hosts.json';
 import type { TextInputProps } from '../../preact/textInput/text-input';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 
-const meta: Meta = {
+const codeExample = String.raw`
+<gs-text-input lapisField="host" placeholderText="Enter host name" initialValue="Homo sapiens"></gs-text-input>`;
+
+const meta: Meta<TextInputProps> = {
     title: 'Input/Text input',
     component: 'gs-text-input',
-    parameters: {
+    parameters: withComponentDocs({
         actions: {
             handles: ['gs-text-input-changed'],
         },
@@ -34,8 +38,15 @@ const meta: Meta = {
                 },
             ],
         },
-    },
+        componentDocs: {
+            tag: 'gs-text-input',
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
     decorators: [withActions],
+    tags: ['autodocs'],
 };
 
 export default meta;

package/src/web-components/input/text-input-component.tsx

@@ -4,16 +4,38 @@ import { TextInput } from '../../preact/textInput/text-input';
 import { PreactLitAdapter } from '../PreactLitAdapter';
 
 /**
- * @fires {CustomEvent<Record<string, string>>} gs-text-input-changed - When the text input has changed
+ *
+ * ## Context
+ *
+ * This component provides a text input field to specify filters for arbitrary fields of this Lapis instance.
+ *
+ * @fires {CustomEvent<Record<string, string>>} gs-text-input-changed
+ * Fired when the input field is changed.
+ * The `details` of this event contain an object with the `lapisField` as key and the input value as value.
+ * Example:
+ * ```
+ * {
+ *  "host": "Homo sapiens"
+ * }
+ *  ```
  */
 @customElement('gs-text-input')
 export class TextInputComponent extends PreactLitAdapter {
+    /**
+     * The initial value to use for this text input.
+     */
     @property()
     initialValue: string | undefined = '';
 
+    /**
+     * The Lapis field name to use for this text input.
+     */
     @property()
     lapisField = '';
 
+    /**
+     * The placeholder text to display in the input field.
+     */
     @property()
     placeholderText: string | undefined = '';