@genspectrum/dashboard-components 0.1.4 → 0.1.5

package/src/preact/mutations/mutations.stories.tsx

@@ -23,6 +23,7 @@ const meta: Meta<MutationsProps> = {
             control: { type: 'check' },
         },
         size: [{ control: 'object' }],
+        headline: { control: 'text' },
     },
 };
 
@@ -37,6 +38,7 @@ const Template = {
                     sequenceType={args.sequenceType}
                     views={args.views}
                     size={args.size}
+                    headline={args.headline}
                 />
             </ReferenceGenomeContext.Provider>
         </LapisUrlContext.Provider>
@@ -50,6 +52,7 @@ export const Default: StoryObj<MutationsProps> = {
         sequenceType: 'nucleotide',
         views: ['grid', 'table', 'insertions'],
         size: { width: '100%', height: '700px' },
+        headline: 'Mutations',
     },
     parameters: {
         fetchMock: {

package/src/preact/mutations/mutations.tsx

@@ -35,15 +35,21 @@ export interface MutationsProps {
     sequenceType: SequenceType;
     views: View[];
     size?: Size;
+    headline?: string;
 }
 
-export const Mutations: FunctionComponent<MutationsProps> = ({ variant, sequenceType, views, size }) => {
+export const Mutations: FunctionComponent<MutationsProps> = ({
+    variant,
+    sequenceType,
+    views,
+    size,
+    headline = 'Mutations',
+}) => {
     const lapis = useContext(LapisUrlContext);
     const { data, error, isLoading } = useQuery(async () => {
         return queryMutationsData(variant, sequenceType, lapis);
     }, [variant, sequenceType, lapis]);
 
-    const headline = 'Mutations';
     if (isLoading) {
         return (
             <Headline heading={headline}>
@@ -197,7 +203,7 @@ const Toolbar: FunctionComponent<ToolbarProps> = ({
                     filename='insertions.csv'
                 />
             )}
-            <Info className='mx-1' content='Info for mutations' />
+            <Info>Info for mutations</Info>
         </div>
     );
 };

package/src/preact/prevalenceOverTime/prevalence-over-time.stories.tsx

@@ -30,6 +30,7 @@ export default {
             control: { type: 'check' },
         },
         size: [{ control: 'object' }],
+        headline: { control: 'text' },
     },
 };
 
@@ -44,6 +45,7 @@ const Template = {
                 views={args.views}
                 confidenceIntervalMethods={args.confidenceIntervalMethods}
                 size={args.size}
+                headline={args.headline}
             />
         </LapisUrlContext.Provider>
     ),
@@ -62,6 +64,7 @@ export const TwoVariants = {
         views: ['bar', 'line', 'bubble', 'table'],
         confidenceIntervalMethods: ['wilson'],
         size: { width: '100%', height: '700px' },
+        headline: 'Prevalence over time',
     },
     parameters: {
         fetchMock: {
@@ -128,6 +131,7 @@ export const OneVariant = {
         views: ['bar', 'line', 'bubble', 'table'],
         confidenceIntervalMethods: ['wilson'],
         size: { width: '100%', height: '700px' },
+        headline: 'Prevalence over time',
     },
     parameters: {
         fetchMock: {

package/src/preact/prevalenceOverTime/prevalence-over-time.tsx

@@ -13,7 +13,7 @@ import { ConfidenceIntervalSelector } from '../components/confidence-interval-se
 import { CsvDownloadButton } from '../components/csv-download-button';
 import { ErrorDisplay } from '../components/error-display';
 import Headline from '../components/headline';
-import Info from '../components/info';
+import Info, { InfoHeadline1, InfoParagraph } from '../components/info';
 import { LoadingDisplay } from '../components/loading-display';
 import { NoDataDisplay } from '../components/no-data-display';
 import { ResizeContainer, type Size } from '../components/resize-container';
@@ -33,6 +33,7 @@ export interface PrevalenceOverTimeProps {
     views: View[];
     confidenceIntervalMethods: ConfidenceIntervalMethod[];
     size?: Size;
+    headline?: string;
 }
 
 export const PrevalenceOverTime: FunctionComponent<PrevalenceOverTimeProps> = ({
@@ -43,6 +44,7 @@ export const PrevalenceOverTime: FunctionComponent<PrevalenceOverTimeProps> = ({
     views,
     confidenceIntervalMethods,
     size,
+    headline = 'Prevalence over time',
 }) => {
     const lapis = useContext(LapisUrlContext);
 
@@ -51,8 +53,6 @@ export const PrevalenceOverTime: FunctionComponent<PrevalenceOverTimeProps> = ({
         [lapis, numerator, denominator, granularity, smoothingWindow],
     );
 
-    const headline = 'Prevalence over time';
-
     if (isLoading) {
         return (
             <Headline heading={headline}>
@@ -202,9 +202,19 @@ const Toolbar: FunctionComponent<ToolbarProps> = ({
                 getData={() => getPrevalenceOverTimeTableData(data, granularity)}
                 filename='prevalence-over-time.csv'
             />
-            <Info className='ml-1' content='Info for prevalence over time' />
+
+            <PrevalenceOverTimeInfo />
         </div>
     );
 };
 
+const PrevalenceOverTimeInfo: FunctionComponent = () => {
+    return (
+        <Info size={{ width: '600px', height: '30vh' }}>
+            <InfoHeadline1>Prevalence over time</InfoHeadline1>
+            <InfoParagraph>Prevalence over time info.</InfoParagraph>
+        </Info>
+    );
+};
+
 export default PrevalenceOverTime;

package/src/preact/relativeGrowthAdvantage/relative-growth-advantage.stories.tsx

@@ -19,6 +19,7 @@ export default {
             control: { type: 'check' },
         },
         size: [{ control: 'object' }],
+        headline: { control: 'text' },
     },
 };
 
@@ -31,6 +32,7 @@ export const Primary = {
                 generationTime={args.generationTime}
                 views={args.views}
                 size={args.size}
+                headline={args.headline}
             />
         </LapisUrlContext.Provider>
     ),
@@ -40,6 +42,7 @@ export const Primary = {
         generationTime: 7,
         views: ['line'],
         size: { width: '100%', height: '700px' },
+        headline: 'Relative growth advantage',
     },
     parameters: {
         fetchMock: {

package/src/preact/relativeGrowthAdvantage/relative-growth-advantage.tsx

@@ -10,7 +10,7 @@ import { type LapisFilter } from '../../types';
 import { LapisUrlContext } from '../LapisUrlContext';
 import { ErrorDisplay } from '../components/error-display';
 import Headline from '../components/headline';
-import Info from '../components/info';
+import Info, { InfoHeadline1, InfoHeadline2, InfoLink, InfoParagraph } from '../components/info';
 import { LoadingDisplay } from '../components/loading-display';
 import { NoDataDisplay } from '../components/no-data-display';
 import { ResizeContainer, type Size } from '../components/resize-container';
@@ -27,6 +27,7 @@ export interface RelativeGrowthAdvantageProps {
     generationTime: number;
     views: View[];
     size?: Size;
+    headline?: string;
 }
 
 export const RelativeGrowthAdvantage: FunctionComponent<RelativeGrowthAdvantageProps> = ({
@@ -35,6 +36,7 @@ export const RelativeGrowthAdvantage: FunctionComponent<RelativeGrowthAdvantageP
     generationTime,
     views,
     size,
+    headline = 'Relative growth advantage',
 }) => {
     const lapis = useContext(LapisUrlContext);
     const [yAxisScaleType, setYAxisScaleType] = useState<ScaleType>('linear');
@@ -44,7 +46,6 @@ export const RelativeGrowthAdvantage: FunctionComponent<RelativeGrowthAdvantageP
         [lapis, numerator, denominator, generationTime, views],
     );
 
-    const headline = 'Relative growth advantage';
     if (isLoading) {
         return (
             <Headline heading={headline}>
@@ -77,6 +78,7 @@ export const RelativeGrowthAdvantage: FunctionComponent<RelativeGrowthAdvantageP
                     yAxisScaleType={yAxisScaleType}
                     setYAxisScaleType={setYAxisScaleType}
                     views={views}
+                    generationTime={generationTime}
                 />
             </Headline>
         </ResizeContainer>
@@ -88,6 +90,7 @@ type RelativeGrowthAdvantageTabsProps = {
     yAxisScaleType: ScaleType;
     setYAxisScaleType: (scaleType: ScaleType) => void;
     views: View[];
+    generationTime: number;
 };
 
 const RelativeGrowthAdvantageTabs: FunctionComponent<RelativeGrowthAdvantageTabsProps> = ({
@@ -95,6 +98,7 @@ const RelativeGrowthAdvantageTabs: FunctionComponent<RelativeGrowthAdvantageTabs
     yAxisScaleType,
     setYAxisScaleType,
     views,
+    generationTime,
 }) => {
     const getTab = (view: View) => {
         switch (view) {
@@ -117,7 +121,11 @@ const RelativeGrowthAdvantageTabs: FunctionComponent<RelativeGrowthAdvantageTabs
 
     const tabs = views.map((view) => getTab(view));
     const toolbar = () => (
-        <RelativeGrowthAdvantageToolbar yAxisScaleType={yAxisScaleType} setYAxisScaleType={setYAxisScaleType} />
+        <RelativeGrowthAdvantageToolbar
+            generationTime={generationTime}
+            yAxisScaleType={yAxisScaleType}
+            setYAxisScaleType={setYAxisScaleType}
+        />
     );
 
     return <Tabs tabs={tabs} toolbar={toolbar} />;
@@ -126,16 +134,53 @@ const RelativeGrowthAdvantageTabs: FunctionComponent<RelativeGrowthAdvantageTabs
 type RelativeGrowthAdvantageToolbarProps = {
     yAxisScaleType: ScaleType;
     setYAxisScaleType: (scaleType: ScaleType) => void;
+    generationTime: number;
 };
 
 const RelativeGrowthAdvantageToolbar: FunctionComponent<RelativeGrowthAdvantageToolbarProps> = ({
     yAxisScaleType,
     setYAxisScaleType,
+    generationTime,
 }) => {
     return (
         <div class='flex'>
             <ScalingSelector yAxisScaleType={yAxisScaleType} setYAxisScaleType={setYAxisScaleType} />
-            <Info className='ml-1' content='Line chart' />
+            <RelativeGrowthAdvantageInfo generationTime={generationTime} />
         </div>
     );
 };
+
+const RelativeGrowthAdvantageInfo: FunctionComponent<{ generationTime: number }> = ({ generationTime }) => {
+    return (
+        <Info size={{ width: '600px', height: '30vh' }}>
+            <InfoHeadline1>Relative growth advantage</InfoHeadline1>
+            <InfoParagraph>
+                If variants spread pre-dominantly by local transmission across demographic groups, this estimate
+                reflects the relative viral intrinsic growth advantage of the focal variant in the selected country and
+                time frame. We report the relative growth advantage per {generationTime} days (in percentage; 0% means
+                equal growth). Importantly, the relative growth advantage estimate reflects the advantage compared to
+                the co-circulating variants. Thus, as new variants spread, the advantage of the focal variant may
+                decrease. Different mechanisms can alter the intrinsic growth rate, including an intrinsic transmission
+                advantage, immune evasion, and a prolonged infectious period. When absolute numbers of a variant are
+                low, the growth advantage may merely reflect the current importance of introductions from abroad or the
+                variant spreading in a particular demographic group. In this case, the estimate does not provide
+                information on any intrinsic fitness advantages.
+            </InfoParagraph>
+            <InfoParagraph>
+                Example: Assume that 10 infections from the focal variant and 100 infections from the co-circulating
+                variants occur today and that the focal variant has a relative growth advantage of 50%. Then, if the
+                number of new infections from the co-circulating variants remains at 100 in {generationTime} days from
+                today, we expect the number of new infections from the focal variant to be 15.
+            </InfoParagraph>
+
+            <InfoHeadline2>Reference</InfoHeadline2>
+            <InfoParagraph>
+                Chen, Chaoran, et al. "Quantification of the spread of SARS-CoV-2 variant B.1.1.7 in Switzerland."
+                Epidemics (2021); doi:{' '}
+                <InfoLink href='https://www.sciencedirect.com/science/article/pii/S1755436521000335?via=ihub'>
+                    10.1016/j.epidem.2021.100480
+                </InfoLink>
+            </InfoParagraph>
+        </Info>
+    );
+};

package/src/web-components/display/aggregate-component.stories.ts

@@ -19,6 +19,7 @@ const meta: Meta<AggregateProps> = {
             control: { type: 'check' },
         },
         size: [{ control: 'object' }],
+        headline: { control: 'text' },
     },
     parameters: withComponentDocs({
         fetchMock: {
@@ -59,6 +60,7 @@ export const Table: StoryObj<AggregateProps> = {
                 .filter=${args.filter}
                 .views=${args.views}
                 .size=${args.size}
+                .headline=${args.headline}
             ></gs-aggregate-component>
         </gs-app>
     `,
@@ -69,5 +71,6 @@ export const Table: StoryObj<AggregateProps> = {
             country: 'USA',
         },
         size: { width: '100%', height: '700px' },
+        headline: 'Aggregate',
     },
 };

package/src/web-components/display/aggregate-component.tsx

@@ -46,8 +46,22 @@ export class AggregateComponent extends PreactLitAdapterWithGridJsStyles {
     @property({ type: Object })
     size: { width?: string; height?: string } | undefined = undefined;
 
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    @property({ type: String })
+    headline: string | undefined = 'Aggregate';
+
     override render() {
-        return <Aggregate fields={this.fields} views={this.views} filter={this.filter} size={this.size} />;
+        return (
+            <Aggregate
+                fields={this.fields}
+                views={this.views}
+                filter={this.filter}
+                size={this.size}
+                headline={this.headline}
+            />
+        );
     }
 }
 

package/src/web-components/display/mutation-comparison-component.stories.ts

@@ -32,6 +32,7 @@ const meta: Meta<MutationComparisonProps> = {
             control: { type: 'check' },
         },
         size: { control: 'object' },
+        headline: { control: 'text' },
     },
     parameters: withComponentDocs({
         componentDocs: {
@@ -54,6 +55,7 @@ const Template: StoryObj<MutationComparisonProps> = {
                 .sequenceType=${args.sequenceType}
                 .views=${args.views}
                 .size=${args.size}
+                .headline=${args.headline}
             ></gs-mutation-comparison-component>
         </gs-app>
     `,
@@ -83,6 +85,7 @@ export const Default: StoryObj<MutationComparisonProps> = {
         sequenceType: 'nucleotide',
         views: ['table', 'venn'],
         size: { width: '100%', height: '700px' },
+        headline: 'Mutation comparison',
     },
     parameters: {
         fetchMock: {

package/src/web-components/display/mutation-comparison-component.tsx

@@ -72,6 +72,12 @@ export class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyle
     @property({ type: Object })
     size: { width?: string; height?: string } | undefined = undefined;
 
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    @property({ type: String })
+    headline: string | undefined = 'Mutation comparison';
+
     override render() {
         return (
             <MutationComparison
@@ -79,6 +85,7 @@ export class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyle
                 sequenceType={this.sequenceType}
                 views={this.views}
                 size={this.size}
+                headline={this.headline}
             />
         );
     }

package/src/web-components/display/mutations-component.stories.ts

@@ -4,15 +4,23 @@ import { html } from 'lit';
 
 import './mutations-component';
 import '../app';
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { LAPIS_URL, NUCLEOTIDE_INSERTIONS_ENDPOINT, NUCLEOTIDE_MUTATIONS_ENDPOINT } from '../../constants';
 import nucleotideInsertions from '../../preact/mutations/__mockData__/nucleotideInsertions.json';
 import nucleotideMutations from '../../preact/mutations/__mockData__/nucleotideMutations.json';
 import { type MutationsProps } from '../../preact/mutations/mutations';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 
+const codeExample = String.raw`
+<gs-mutations
+    variant='{ "country": "Switzerland", "pangoLineage": "B.1.1.7", "dateTo": "2022-01-01" }'
+    sequenceType="nucleotide"
+    views='["grid", "table", "insertions"]'
+></gs-mutations>`;
+
 const meta: Meta<MutationsProps> = {
     title: 'Visualization/Mutations',
-    component: 'gs-mutations',
+    component: 'gs-mutations-component',
     argTypes: {
         variant: { control: 'object' },
         sequenceType: {
@@ -24,7 +32,24 @@ const meta: Meta<MutationsProps> = {
             control: { type: 'check' },
         },
         size: { control: 'object' },
+        headline: { control: 'text' },
+    },
+    args: {
+        variant: { country: 'Switzerland', pangoLineage: 'B.1.1.7', dateTo: '2022-01-01' },
+        sequenceType: 'nucleotide',
+        views: ['grid', 'table', 'insertions'],
+        size: { width: '100%', height: '700px' },
+        headline: 'Mutations',
     },
+    parameters: withComponentDocs({
+        componentDocs: {
+            tag: 'gs-mutations-component',
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
+    tags: ['autodocs'],
 };
 
 export default meta;
@@ -37,6 +62,7 @@ const Template: StoryObj<MutationsProps> = {
                 .sequenceType=${args.sequenceType}
                 .views=${args.views}
                 .size=${args.size}
+                .headline=${args.headline}
             ></gs-mutations-component>
         </gs-app>
     `,
@@ -44,12 +70,6 @@ const Template: StoryObj<MutationsProps> = {
 
 export const Default: StoryObj<MutationsProps> = {
     ...Template,
-    args: {
-        variant: { country: 'Switzerland', pangoLineage: 'B.1.1.7', dateTo: '2022-01-01' },
-        sequenceType: 'nucleotide',
-        views: ['grid', 'table', 'insertions'],
-        size: { width: '100%', height: '700px' },
-    },
     parameters: {
         fetchMock: {
             mocks: [

package/src/web-components/display/mutations-component.tsx

@@ -2,18 +2,54 @@ import { customElement, property } from 'lit/decorators.js';
 
 import { Mutations, type View } from '../../preact/mutations/mutations';
 import { type LapisFilter, type SequenceType } from '../../types';
+import type { Equals, Expect } from '../../utils/typeAssertions';
 import { PreactLitAdapterWithGridJsStyles } from '../PreactLitAdapterWithGridJsStyles';
 
+/**
+ * This component displays mutations (substitutions, deletions and insertions) for a given variant.
+ *
+ * ## Views
+ *
+ * ### Table View
+ *
+ * The table view shows all substitutions and deletions for the given variant.
+ * It shows the type (substitution or deletion), the total count of the mutation
+ * and the proportion of the mutation in the variant.
+ * The proportion is relative to the total number of sequences matching
+ * the specified sequence filters with non-ambiguous reads at that position.
+ *
+ * The proportion interval filter can be used to filter the displayed mutations on client side.
+ *
+ * ### Grid View
+ *
+ * The grid view shows the proportion of each sequence symbol (nucleotide or amino acid) for each position that has a mutation.
+ * Only positions with at least one mutation in the selected proportion interval are shown.
+ *
+ * ### Insertions View
+ *
+ * The insertions view shows the count of all insertions for the given variant.
+ *
+ */
 @customElement('gs-mutations-component')
 export class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
+    /**
+     * The `variant` will be sent as is to LAPIS to filter the mutation data.
+     * It must be a valid LAPIS filter object.
+     */
     @property({ type: Object })
-    variant: LapisFilter = { displayName: '' };
+    variant: Record<string, string | number | null | boolean> = { displayName: '' };
 
+    /**
+     * The type of the sequence for which the mutations should be shown.
+     */
     @property({ type: String })
-    sequenceType: SequenceType = 'nucleotide';
+    sequenceType: 'nucleotide' | 'amino acid' = 'nucleotide';
 
+    /**
+     * A list of tabs with views that this component should provide.
+     */
     @property({ type: Array })
-    views: View[] = ['table', 'grid'];
+    views: ('table' | 'grid' | 'insertions')[] = ['table', 'grid'];
 
     /**
      * The size of the component.
@@ -26,9 +62,21 @@ export class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
     @property({ type: Object })
     size: { width?: string; height?: string } | undefined = undefined;
 
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    @property({ type: String })
+    headline: string | undefined = 'Mutations';
+
     override render() {
         return (
-            <Mutations variant={this.variant} sequenceType={this.sequenceType} views={this.views} size={this.size} />
+            <Mutations
+                variant={this.variant}
+                sequenceType={this.sequenceType}
+                views={this.views}
+                size={this.size}
+                headline={this.headline}
+            />
         );
     }
 }
@@ -38,3 +86,9 @@ declare global {
         'gs-mutations-component': MutationsComponent;
     }
 }
+
+/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */
+type VariantsMatches = Expect<Equals<typeof MutationsComponent.prototype.variant, LapisFilter>>;
+type SequenceTypeMatches = Expect<Equals<typeof MutationsComponent.prototype.sequenceType, SequenceType>>;
+type ViewsMatches = Expect<Equals<typeof MutationsComponent.prototype.views, View[]>>;
+/* eslint-enable @typescript-eslint/no-unused-vars, no-unused-vars */

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

@@ -4,6 +4,7 @@ import { html } from 'lit';
 
 import '../app';
 import './prevalence-over-time-component';
+import { withComponentDocs } from '../../../.storybook/ComponentDocsBlock';
 import { AGGREGATED_ENDPOINT, LAPIS_URL } from '../../constants';
 import denominator from '../../preact/prevalenceOverTime/__mockData__/denominator.json';
 import denominatorOneVariant from '../../preact/prevalenceOverTime/__mockData__/denominatorOneVariant.json';
@@ -13,6 +14,16 @@ import numeratorOneVariant from '../../preact/prevalenceOverTime/__mockData__/nu
 import { type PrevalenceOverTimeProps } from '../../preact/prevalenceOverTime/prevalence-over-time';
 import { withinShadowRoot } from '../withinShadowRoot.story';
 
+const codeExample = String.raw`
+<gs-prevalence-over-time
+    numerator='[{ "displayName": "EG", "country": "USA", "pangoLineage": "EG*" }, { "displayName": "JN.1", "country": "USA", "pangoLineage": "JN.1*" }]'
+    denominator='{ "country": "USA", "displayName": "All" }'
+    granularity="month"
+    smoothingWindow="0"
+    views='["bar", "line", "bubble", "table"]'
+    confidenceIntervalMethods='["wilson"]'
+></gs-prevalence-over-time>`;
+
 const meta: Meta<PrevalenceOverTimeProps> = {
     title: 'Visualization/Prevalence over time',
     component: 'gs-prevalence-over-time',
@@ -33,7 +44,17 @@ const meta: Meta<PrevalenceOverTimeProps> = {
             control: { type: 'check' },
         },
         size: [{ control: 'object' }],
+        headline: { control: 'text' },
     },
+    parameters: withComponentDocs({
+        componentDocs: {
+            tag: 'gs-prevalence-over-time',
+            opensShadowDom: true,
+            expectsChildren: false,
+            codeExample,
+        },
+    }),
+    tags: ['autodocs'],
 };
 
 export default meta;
@@ -49,6 +70,7 @@ const Template: StoryObj<PrevalenceOverTimeProps> = {
                 .views=${args.views}
                 .confidenceIntervalMethods=${args.confidenceIntervalMethods}
                 .size=${args.size}
+                .headline=${args.headline}
             ></gs-prevalence-over-time>
         </gs-app>
     `,
@@ -67,6 +89,7 @@ export const TwoVariants: StoryObj<PrevalenceOverTimeProps> = {
         views: ['bar', 'line', 'bubble', 'table'],
         confidenceIntervalMethods: ['wilson'],
         size: { width: '100%', height: '700px' },
+        headline: 'Prevalence over time',
     },
     parameters: {
         fetchMock: {
@@ -133,6 +156,7 @@ export const OneVariant: StoryObj<PrevalenceOverTimeProps> = {
         views: ['bar', 'line', 'bubble', 'table'],
         confidenceIntervalMethods: ['wilson'],
         size: { width: '100%', height: '700px' },
+        headline: 'Prevalence over time',
     },
     parameters: {
         fetchMock: {