@genspectrum/dashboard-components 0.1.3 → 0.1.5

package/dist/genspectrum-components.d.ts

@@ -8,10 +8,6 @@ import { ReactiveElement } from '@lit/reactive-element';
 import { TemplateResult } from 'lit-html';
 
 /**
- * ## Tag
- *
- * `gs-aggregate-component`
- *
  * ## Context
  *
  * This component displays aggregated data, which can provide an overview of the underlying data.
@@ -30,46 +26,127 @@ export declare class AggregateComponent extends PreactLitAdapterWithGridJsStyles
      * The proportion represents the ratio of the aggregated value to the total count of the data
      * (considering the applied filter).
      */
-    views: View_5[];
+    views: View[];
     /**
      * The filter to apply to the data.
      */
     filter: LapisFilter;
+    /**
+     * The size of the component.
+     *
+     * If not set, the component will take the full width of its container with height 700px.
+     *
+     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
+     * If the unit is %, the size will be relative to the container of the component.
+     */
+    size: {
+        width?: string;
+        height?: string;
+    } | undefined;
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    headline: string | undefined;
     render(): JSX_2.Element;
 }
 
+/**
+ * ## Context
+ *
+ * This component provides the main application context.
+ * All other `gs-*` components must be (possibly nested) children of this component.
+ * It makes use of the [Lit Context](https://lit.dev/docs/data/context/) to
+ * - provide the URL to the LAPIS instance to all its children
+ * - fetch the reference genomes from LAPIS and provide it to all its children
+ *
+ * This will show an error message if the reference genome cannot be fetched
+ * (e.g., due to an invalid LAPIS URL).
+ *
+ * ## Shadow DOM
+ *
+ * This component does __not__ use a shadow DOM. Children of this component will be rendered directly in the light DOM.
+ */
 export declare class App extends LitElement {
+    /**
+     * The URL of the LAPIS instance that all children of this component will use.
+     */
     lapis: string;
-    referenceGenome: ReferenceGenome;
-    private updateReferenceGenome;
+    /* Excluded from this release type: referenceGenome */
+    /* Excluded from this release type: updateReferenceGenome */
     render(): TemplateResult<1> | undefined;
     createRenderRoot(): this;
 }
 
-declare type ConfidenceIntervalMethod = 'wilson' | 'none';
-
-declare type CustomSelectOption = {
-    label: string;
-    dateFrom: string;
-    dateTo: string;
-};
-
 /**
- * @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`.
  */
 export declare class DateRangeSelectorComponent extends PreactLitAdapter {
-    customSelectOptions: CustomSelectOption[];
+    /**
+     * 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`.
+     */
+    customSelectOptions: {
+        label: string;
+        dateFrom: string;
+        dateTo: string;
+    }[];
+    /**
+     * The `dateFrom` value to use in the `allTimes` preset in the format `YYYY-MM-DD`.
+     */
     earliestDate: string | undefined;
+    /**
+     * 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'`.
+     */
+    initialValue: 'custom' | 'allTimes' | 'last2Weeks' | 'lastMonth' | 'last2Months' | 'last3Months' | 'last6Months' | string | undefined;
     render(): JSX_2.Element;
 }
 
+declare class Deletion implements Mutation {
+    readonly segment: string | undefined;
+    readonly valueAtReference: string | undefined;
+    readonly position: number;
+    readonly code: string;
+    constructor(segment: string | undefined, valueAtReference: string | undefined, position: number);
+    equals(other: Mutation): boolean;
+    toString(): string;
+    static parse(mutationStr: string): Deletion | null;
+}
+
+declare class Insertion implements Mutation {
+    readonly segment: string | undefined;
+    readonly position: number;
+    readonly insertedSymbols: string;
+    readonly code: string;
+    constructor(segment: string | undefined, position: number, insertedSymbols: string);
+    equals(other: Mutation): boolean;
+    toString(): string;
+    static parse(mutationStr: string): Insertion | null;
+}
+
 declare type LapisFilter = Record<string, string | number | null | boolean>;
 
 /**
- * ## Tag
- *
- * `gs-location-filter`
- *
  * ## Context
  *
  * This component provides an input field to specify filters for locations.
@@ -101,7 +178,7 @@ export declare class LocationFilterComponent extends PreactLitAdapter {
      * The initial value to use for this location filter.
      * Must be of the form `valueForField1 / valueForField2 / ... / valueForFieldN`.
      */
-    value: string;
+    initialValue: string;
     /**
      * The fields to display in the location filter, in hierarchical order.
      * The top-level field should be the first entry in the array.
@@ -112,37 +189,193 @@ export declare class LocationFilterComponent extends PreactLitAdapter {
     render(): JSX_2.Element;
 }
 
-export declare class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyles {
-    variants: MutationComparisonVariant[];
-    sequenceType: SequenceType;
-    views: View[];
-    render(): JSX_2.Element;
+declare interface Mutation {
+    readonly segment: string | undefined;
+    readonly position: number;
+    readonly code: string;
+    equals(other: Mutation): boolean;
+    toString(): string;
 }
 
-declare interface MutationComparisonVariant {
-    lapisFilter: LapisFilter;
-    displayName: string;
+/**
+ * This component allows to compare mutations between different variants.
+ * A variant is defined by its LAPIS filter.
+ *
+ * It only shows substitutions and deletions, it does not show insertions.
+ *
+ * ## Views
+ *
+ * ### Table View
+ *
+ * The table view shows mutations
+ * and the proportions with which the mutation occurs in the respective variant.
+ * It only shows mutations that are present in at least one of the variants
+ * and where the proportion is within the selected proportion interval for at least one variant.
+ *
+ * ### Venn View
+ *
+ * The Venn view shows the overlap of mutations between the variants in a Venn diagram.
+ * A variant is considered to have a certain mutation,
+ * if the proportion of the mutation in the variant is within the selected proportion interval.
+ * Thus, changing the proportion interval may change a mutations from being "common" between variant
+ * to being "for one variant only".
+ */
+export declare class MutationComparisonComponent extends PreactLitAdapterWithGridJsStyles {
+    /**
+     * An array of variants to compare.
+     *
+     * The `lapisFilter` will be sent as is to LAPIS to filter the mutation data.
+     * It must be a valid LAPIS filter object.
+     *
+     * The `displayName` will be used as the label for the variant in the views.
+     * It should be human-readable.
+     */
+    variants: {
+        lapisFilter: Record<string, string | number | null | boolean>;
+        displayName: string;
+    }[];
+    /**
+     * The type of the sequence for which the mutations should be shown.
+     */
+    sequenceType: 'nucleotide' | 'amino acid';
+    /**
+     * A list of tabs with views that this component should provide.
+     */
+    views: ('table' | 'venn')[];
+    /**
+     * The size of the component.
+     *
+     * If not set, the component will take the full width of its container with height 700px.
+     *
+     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
+     * If the unit is %, the size will be relative to the container of the component.
+     */
+    size: {
+        width?: string;
+        height?: string;
+    } | undefined;
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    headline: string | undefined;
+    render(): JSX_2.Element;
 }
 
 /**
- * @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
  */
 export declare 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.
+     */
+    initialValue: SelectedMutationFilterStrings | string[] | undefined;
     render(): JSX_2.Element;
 }
 
+/**
+ * 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.
+ *
+ */
 export declare class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
-    variant: LapisFilter;
-    sequenceType: SequenceType;
-    views: View_2[];
+    /**
+     * The `variant` will be sent as is to LAPIS to filter the mutation data.
+     * It must be a valid LAPIS filter object.
+     */
+    variant: Record<string, string | number | null | boolean>;
+    /**
+     * The type of the sequence for which the mutations should be shown.
+     */
+    sequenceType: 'nucleotide' | 'amino acid';
+    /**
+     * A list of tabs with views that this component should provide.
+     */
+    views: ('table' | 'grid' | 'insertions')[];
+    /**
+     * The size of the component.
+     *
+     * If not set, the component will take the full width of its container with height 700px.
+     *
+     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
+     * If the unit is %, the size will be relative to the container of the component.
+     */
+    size: {
+        width?: string;
+        height?: string;
+    } | undefined;
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    headline: string | undefined;
     render(): JSX_2.Element;
 }
 
-declare type NamedLapisFilter = LapisFilter & {
-    displayName: string;
-};
-
 declare abstract class PreactLitAdapter extends ReactiveElement {
     static styles: CSSResult[];
     /* Excluded from this release type: lapis */
@@ -155,13 +388,99 @@ declare abstract class PreactLitAdapterWithGridJsStyles extends PreactLitAdapter
     static styles: CSSResult[];
 }
 
+/**
+ * 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.
+ */
 export declare class PrevalenceOverTimeComponent extends PreactLitAdapterWithGridJsStyles {
-    numerator: NamedLapisFilter | NamedLapisFilter[];
-    denominator: NamedLapisFilter;
-    granularity: TemporalGranularity;
+    /**
+     * 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.
+     */
+    numerator: (Record<string, string | number | null | boolean> & {
+        displayName: string;
+    }) | (Record<string, string | number | null | boolean> & {
+        displayName: string;
+    })[];
+    /**
+     * The variant that the variants in `numerator` are compared to.
+     */
+    denominator: Record<string, string | number | null | boolean> & {
+        displayName: string;
+    };
+    /**
+     * The granularity of the time axis.
+     */
+    granularity: 'day' | 'week' | 'month' | 'year';
+    /**
+     * 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)`.
+     */
     smoothingWindow: number;
-    views: View_3[];
-    confidenceIntervalMethods: ConfidenceIntervalMethod[];
+    /**
+     * A list of tabs with views that this component should provide.
+     */
+    views: ('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.
+     */
+    confidenceIntervalMethods: ('wilson' | 'none')[];
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    headline: string | undefined;
+    /**
+     * The size of the component.
+     *
+     * If not set, the component will take the full width of its container with height 700px.
+     *
+     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
+     * If the unit is %, the size will be relative to the container of the component.
+     */
+    size: {
+        width?: string;
+        height?: string;
+    } | undefined;
     render(): JSX_2.Element;
 }
 
@@ -208,36 +527,123 @@ declare const referenceGenomeResponse: default_2.ZodObject<{
     }[];
 }>;
 
+/**
+ * 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.
+ */
 export declare class RelativeGrowthAdvantageComponent extends PreactLitAdapter {
-    numerator: LapisFilter;
-    denominator: LapisFilter;
+    /**
+     * The LAPIS filter for the focal variant.
+     */
+    numerator: Record<string, string | number | null | boolean>;
+    /**
+     * The LAPIS filter for the variant that the focal variant (`numerator`) should be compared to.
+     */
+    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.
+     */
     generationTime: number;
-    views: View_4[];
+    /**
+     * A list of tabs with views that this component should provide.
+     */
+    views: 'line'[];
+    /**
+     * The headline of the component. Set to an empty string to hide the headline.
+     */
+    headline: string | undefined;
+    /**
+     * The size of the component.
+     *
+     * If not set, the component will take the full width of its container with height 700px.
+     *
+     * The width and height should be a string with a unit in css style, e.g. '100%', '500px' or '50vh'.
+     * If the unit is %, the size will be relative to the container of the component.
+     */
+    size: {
+        width?: string;
+        height?: string;
+    } | undefined;
     render(): JSX_2.Element;
 }
 
-declare type SequenceType = 'nucleotide' | 'amino acid';
+declare type SelectedFilters = {
+    nucleotideMutations: (Substitution | Deletion)[];
+    aminoAcidMutations: (Substitution | Deletion)[];
+    nucleotideInsertions: Insertion[];
+    aminoAcidInsertions: Insertion[];
+};
+
+declare type SelectedMutationFilterStrings = {
+    [Key in keyof SelectedFilters]: string[];
+};
 
-declare type TemporalGranularity = 'day' | 'week' | 'month' | 'year';
+declare class Substitution implements Mutation {
+    readonly segment: string | undefined;
+    readonly valueAtReference: string | undefined;
+    readonly substitutionValue: string | undefined;
+    readonly position: number;
+    readonly code: string;
+    constructor(segment: string | undefined, valueAtReference: string | undefined, substitutionValue: string | undefined, position: number);
+    equals(other: Mutation): boolean;
+    toString(): string;
+    static parse(mutationStr: string): Substitution | null;
+}
 
 /**
- * @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"
+ * }
+ *  ```
  */
 export declare class TextInputComponent extends PreactLitAdapter {
+    /**
+     * The initial value to use for this text input.
+     */
+    initialValue: string | undefined;
+    /**
+     * The Lapis field name to use for this text input.
+     */
     lapisField: string;
-    placeholderText: string;
+    /**
+     * The placeholder text to display in the input field.
+     */
+    placeholderText: string | undefined;
     render(): JSX_2.Element;
 }
 
-declare type View = 'table' | 'venn';
-
-declare type View_2 = 'table' | 'grid' | 'insertions';
-
-declare type View_3 = 'bar' | 'line' | 'bubble' | 'table';
-
-declare type View_4 = 'line';
-
-declare type View_5 = 'table';
+declare type View = 'table';
 
 export { }
 
@@ -299,31 +705,31 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-mutation-filter': TextInputComponent;
+        'gs-location-filter': LocationFilterComponent;
     }
     interface HTMLElementEventMap {
-        'gs-mutation-filter-changed': CustomEvent<SelectedMutationFilterStrings>;
-        'gs-mutation-filter-on-blur': CustomEvent<SelectedMutationFilterStrings>;
+        'gs-location-changed': CustomEvent<Record<string, string>>;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-location-filter': LocationFilterComponent;
+        'gs-text-input': TextInputComponent;
     }
     interface HTMLElementEventMap {
-        'gs-location-changed': CustomEvent<Record<string, string>>;
+        'gs-text-input-changed': CustomEvent<Record<string, string>>;
     }
 }
 
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-text-input': TextInputComponent;
+        'gs-mutation-filter': TextInputComponent;
     }
     interface HTMLElementEventMap {
-        'gs-text-input-changed': CustomEvent<Record<string, string>>;
+        'gs-mutation-filter-changed': CustomEvent<SelectedMutationFilterStrings>;
+        'gs-mutation-filter-on-blur': CustomEvent<SelectedMutationFilterStrings>;
     }
 }