@genspectrum/dashboard-components 0.1.4 → 0.1.5

package/dist/genspectrum-components.d.ts

@@ -26,7 +26,7 @@ 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_4[];
+    views: View[];
     /**
      * The filter to apply to the data.
      */
@@ -43,6 +43,10 @@ export declare class AggregateComponent extends PreactLitAdapterWithGridJsStyles
         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;
 }
 
@@ -73,21 +77,48 @@ export declare class App extends LitElement {
     createRenderRoot(): this;
 }
 
-declare type ConfidenceIntervalMethod = 'wilson' | 'none';
-
-declare type CustomSelectOption<CustomLabel extends string> = {
-    label: CustomLabel;
-    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<CustomLabel extends string> extends PreactLitAdapter {
-    customSelectOptions: CustomSelectOption<CustomLabel>[];
+export declare 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`.
+     */
+    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;
-    initialValue: PresetOptionValues | CustomLabel | 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;
 }
 
@@ -223,22 +254,109 @@ export declare class MutationComparisonComponent extends PreactLitAdapterWithGri
         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[];
+    /**
+     * 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.
      *
@@ -251,13 +369,13 @@ export declare class MutationsComponent extends PreactLitAdapterWithGridJsStyles
         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 */
@@ -270,39 +388,87 @@ declare abstract class PreactLitAdapterWithGridJsStyles extends PreactLitAdapter
     static styles: CSSResult[];
 }
 
-declare type PresetOptionValues = keyof typeof presets;
-
-declare const presets: {
-    custom: {
-        label: string;
-    };
-    allTimes: {
-        label: string;
-    };
-    last2Weeks: {
-        label: string;
-    };
-    lastMonth: {
-        label: string;
-    };
-    last2Months: {
-        label: string;
-    };
-    last3Months: {
-        label: string;
-    };
-    last6Months: {
-        label: string;
-    };
-};
-
+/**
+ * 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_2[];
-    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.
      *
@@ -361,11 +527,52 @@ 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_3[];
+    /**
+     * 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.
      *
@@ -392,8 +599,6 @@ declare type SelectedMutationFilterStrings = {
     [Key in keyof SelectedFilters]: string[];
 };
 
-declare type SequenceType = 'nucleotide' | 'amino acid';
-
 declare class Substitution implements Mutation {
     readonly segment: string | undefined;
     readonly valueAtReference: string | undefined;
@@ -406,25 +611,39 @@ declare class Substitution implements Mutation {
     static parse(mutationStr: string): Substitution | null;
 }
 
-declare type TemporalGranularity = 'day' | 'week' | 'month' | 'year';
-
 /**
- * @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;
+    /**
+     * The placeholder text to display in the input field.
+     */
     placeholderText: string | undefined;
     render(): JSX_2.Element;
 }
 
-declare type View = 'table' | 'grid' | 'insertions';
-
-declare type View_2 = 'bar' | 'line' | 'bubble' | 'table';
-
-declare type View_3 = 'line';
-
-declare type View_4 = 'table';
+declare type View = 'table';
 
 export { }
 
@@ -473,7 +692,7 @@ declare global {
 
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-date-range-selector': DateRangeSelectorComponent<string>;
+        'gs-date-range-selector': DateRangeSelectorComponent;
     }
     interface HTMLElementEventMap {
         'gs-date-range-changed': CustomEvent<{