npm - @genspectrum/dashboard-components - Versions diffs - 0.19.7 → 0.19.9 - Mend

@genspectrum/dashboard-components 0.19.7 → 0.19.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/src/web-components/tutorials/CreateYourFirstOwnDashboard.mdx ADDED Viewed

@@ -0,0 +1,85 @@
+import { Meta } from '@storybook/blocks';
+<Meta title='Tutorials/Create your first own dashboard' />
+# Create your first own dashboard
+In this tutorial, you’ll learn how to integrate our `visualization` components into your HTML page.
+We’ll walk through building a simple dashboard that displays the number of sequences over time, along with some general statistics.
+This example serves as a foundation for your own dashboards—you can easily extend it by adding more components as needed.
+The data for these components must be provided by a LAPIS instance.
+For this tutorial, we’ll use one of our own [LAPIS](https://lapis.cov-spectrum.org/open/v2/docs/) instances, but you’re free to use any LAPIS instance that supplies the required data.
+## Create your HTML page
+Let's start by creating a simple HTML page. If you already have one, you can skip this step.
+Name the file `index.html` and add the following code. This will be the main file for your dashboard.
+```html
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>My dashboard</title>
+    </head>
+    <body>
+        We will fill this section later
+    </body>
+</html>
+```
+## Include the dashboard components
+To use the components, you need to include the dashboard bundle in your HTML file.
+Add the following code to the `head` section:
+```html
+<script
+    type="module"
+    src="https://unpkg.com/@genspectrum/dashboard-components@latest/standalone-bundle/dashboard-components.js"
+></script>
+```
+This approach uses a standalone bundle, which includes all the code for the components in a single step.
+It is the easiest way to get started, although the bundle size is larger.
+Alternatively, you can use the components as modules, but this requires a build step.
+For more information, see the "Use the Components with Plain JavaScript" tutorial.
+## Add the dashboard components to your HTML file
+We are now ready to add the components to our HTML file.
+You can do this by adding the following code to the `body` section of your HTML file:
+```html
+<gs-app lapis="https://lapis.genspectrum.org/open/v2">
+    <h2>Statistics</h2>
+    <gs-statistics numeratorFilter='{"pangoLineage": "EG*"}' denominatorFilter="{}" width="100%"></gs-statistics>
+    <h2>Number of sequences over time</h2>
+    <gs-number-sequences-over-time
+        lapisFilters='[{ "displayName": "EG", "lapisFilter": { "pangoLineage": "EG*" } }]'
+        lapisDateField="date"
+        views='["bar", "line", "table"]'
+        width="100%"
+        granularity="month"
+        smoothingWindow="0"
+        pageSize="10"
+    ></gs-number-sequences-over-time>
+</gs-app>
+```
+Here, we are using three components:
+- `gs-app`: This is the main component that wraps all the other components. It is used to provide the context for the other components. Each of our components needs to be wrapped in this component.
+  It provides the `lapis` attribute, which is the URL of the LAPIS server. This is the server that provides the data for the components. In this example, we are using the LAPIS server for open SARS-CoV-2 data.
+- `gs-statistics` and `gs-number-sequences-over-time`: Visualization components that display data from the LAPIS server.
+You can find more examples and detailed descriptions of each component in our documentation.
+You now have your first dashboard. Open the `index.html` file in your browser to see it in action.
+Feel free to change some parameters to see how they affect the dashboard, or explore our Storybook for more examples.
+The parameters are currently fixed in the HTML file.
+If you want users to be able to change them—especially the filters—we also provide input components.
+To use them, add the input components to your HTML and connect them with JavaScript.
+For more information, see the "Use the Components with Plain JavaScript" tutorial.

package/src/web-components/tutorials/UseTheComponentsWithPlainJavaScript.mdx ADDED Viewed

@@ -0,0 +1,140 @@
+import { Meta } from '@storybook/blocks';
+<Meta title='Tutorials/Use the components with plain JavaScript' />
+# Use the components in plain JavaScript
+In this tutorial, we will show you how to use dashboard components with plain JavaScript,
+which might be useful if you want to use the components in a framework like Svelte or Vue.js.
+For React, we have a separate tutorial.
+We will create a simple dashboard that shows the number of sequences over time and allows you to filter the data by location.
+You can find a similar working example in our [examples directory](https://github.com/GenSpectrum/dashboard-components/tree/4ae6a7a9aab3c4c583704f49845c042bcbb6d311/examples/plainJavascript)
+The data for these components must be provided by a LAPIS instance.
+For this tutorial, we’ll use one of our own [LAPIS](https://lapis.cov-spectrum.org/open/v2/docs/) instances, but you’re free to use any LAPIS instance that supplies the required data.
+## Prerequisites
+We assume that you already have a working environment with the following:
+- Node.js installed
+- A package manager (npm or yarn)
+- A html file where you want to use the components. Here we will use a file called `index.html`.
+For this tutorial, we use [Vite](https://vite.dev/guide/#index-html-and-project-root) as a build tool. You can use any other build tool, but this will not be covered in this tutorial.
+## Install the dashboard components
+First, install the components by running the following command in your terminal:
+```bash
+npm install @genspectrum/dashboard-components
+```
+Then, load the components in your HTML file by adding the following code to the `head` section of your HTML file:
+```html
+<script type="module" src="node_modules/@genspectrum/dashboard-components/dist/components.js"></script>
+```
+**Note**: Currently, there is an issue with one of our dependencies. To resolve this, create an additional file called `vite.config.js` and add the following code to it:
+```javascript
+import { defineConfig } from 'vite';
+export default defineConfig({
+    optimizeDeps: {
+        include: ['leaflet'],
+    },
+});
+```
+## Add the dashboard components to your HTML file
+You can now add components to your HTML file by adding, for example, the following code to the `body` section of your HTML file:
+```html
+<gs-app lapis="https://lapis.genspectrum.org/open/v2">
+    <h2>Filter By Location</h2>
+    <gs-location-filter
+        fields='["region", "country", "division"]'
+        width="100%"
+        placeholderText="Enter a location"
+    ></gs-location-filter>
+    <h2>Number of sequences over time</h2>
+    <gs-number-sequences-over-time
+        lapisFilters='[{ "displayName": "Data", "lapisFilter": {}}]'
+        lapisDateField="date"
+        views='["bar", "line", "table"]'
+        width="100%"
+        granularity="month"
+        smoothingWindow="0"
+        pageSize="10"
+    ></gs-number-sequences-over-time>
+</gs-app>
+```
+As you can see, we are using three components:
+- `gs-app`: This is the main component that wraps all the other components, providing the context for them. Each of our components must be wrapped in this component.
+  It provides the `lapis` prop, which is the URL of the LAPIS server, the server that provides the data for the components. In this example, we are using the LAPIS server for open SARS-CoV-2 data.
+- `gs-location-filter`: This is an example of our input components, which are used to create LAPIS filters for the visualization components. In this case, it is used to filter the data by location.
+- `gs-number-sequences-over-time`: This is an example of our visualization components, which are used to visualize the data from the LAPIS server. In this case, it shows the number of sequences over time.
+You can find more examples and descriptions of each component in our documentation.
+Now you can look at your dashboard by running vite in your terminal:
+```bash
+npx vite dev
+```
+If you only want to use the visualization components, you are finished here. If you want to use the input components, you will need to add some additional code to make them work.
+## Add interactivity between the components
+Each of our `input` components emits an event when the user selects a new value. You can listen to this event and update the `visualization` components accordingly.
+First, you need to add a script tag to your HTML file and listen to the events. This should only be done after the page has loaded. You can do this by adding the following code below the `gs-app` component:
+```html
+<script>
+    document.addEventListener('DOMContentLoaded', function () {
+        document.querySelector('gs-location-filter').addEventListener('gs-location-changed', (event) => {
+            const newLocationFilter = event.detail;
+            console.log('newLocationFilter', newLocationFilter);
+        });
+    });
+</script>
+```
+You should now see the location value in the browser console after changing the value in the location filter.
+You can find more information about event listeners in the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener).
+Now, you need to add the code to update the `gs-number-sequences-over-time` component.
+There, you need to update the `lapisFilters`.
+You first get the current filter values of the component, and then you add the new location filter to each of them.
+```html
+<script>
+    document.addEventListener('DOMContentLoaded', function () {
+        document.querySelector('gs-location-filter').addEventListener('gs-location-changed', (event) => {
+            const newLocationFilter = event.detail;
+            const numberOfSequencesOverTimeComponent = document.querySelectorAll('gs-number-sequences-over-time');
+            numberOfSequencesOverTimeComponent.forEach((element) => {
+                const oldFilters = JSON.parse(element.getAttribute('lapisFilters'));
+                const newFilters = oldFilters.map((filter) => {
+                    return {
+                        ...filter,
+                        lapisFilter: {
+                            ...filter.lapisFilter,
+                            ...newLocationFilter,
+                        },
+                    };
+                });
+                element.setAttribute('lapisFilters', JSON.stringify(newFilters));
+            });
+        });
+    });
+</script>
+```
+Now you can see, after running vite that the `gs-number-sequences-over-time` component updates when you select a new location in the `gs-location-filter` component.

package/src/web-components/tutorials/UseTheComponentsWithReact.mdx ADDED Viewed

@@ -0,0 +1,166 @@
+import { Meta } from '@storybook/blocks';
+<Meta title='Tutorials/Use the components with React' />
+# Use the components with React
+In this tutorial, we will show you how to use dashboard components with React.
+We will create a simple dashboard that shows the prevalence of a specific variant over time and allows you to filter the data by location.
+You can find a similar working example in our [examples directory](https://github.com/GenSpectrum/dashboard-components/tree/4ae6a7a9aab3c4c583704f49845c042bcbb6d311/examples/React).
+The data for these components must be provided by a LAPIS instance.
+For this tutorial, we’ll use one of our own [LAPIS](https://lapis.cov-spectrum.org/open/v2/docs/) instances, but you’re free to use any LAPIS instance that supplies the required data.
+## Prerequisites and setup
+We assume that you already have a working React environment. We have tested this with React 18.2.0
+First, install the components by running the following command in your terminal:
+```bash
+npm install @genspectrum/dashboard-components
+```
+Then, import the components in your React entry point script (the tsx file that is included in your `index.html` file):
+```javascript
+import '@genspectrum/dashboard-components/components';
+```
+## Add the dashboard components to your React file
+You can now use the components in your own React components.
+Here we create a new component called `Dashboard` that will contain all the logic.
+```javascript
+function Dashboard() {
+    return (
+        <gs-app lapis='https://lapis.cov-spectrum.org/open/v2/'>
+            <h2>Filter By Location</h2>
+            <gs-location-filter
+                fields='["region", "country", "division", "location"]'
+                width='100%'
+                placeholderText='Enter a location'
+            ></gs-location-filter>
+            <h2>Prevalence over time</h2>
+            <gs-prevalence-over-time
+                numeratorFilters='[{"displayName":"EG","lapisFilter":{"country":"USA","pangoLineage":"EG*","dateFrom":"2023-01-01"}},{"displayName":"JN.1","lapisFilter":{"country":"USA","pangoLineage":"JN.1*","dateFrom":"2023-01-01"}}]'
+                denominatorFilter='{"country":"USA","dateFrom":"2023-01-01"}'
+                lapisDateField='date'
+                granularity='day'
+                smoothingWindow='7'
+                views='["line", "table"]'
+            ></gs-prevalence-over-time>
+        </gs-app>
+    );
+}
+```
+As you can see, we are using three components:
+- `gs-app`: This is the main component that wraps all the other components, providing the context for them. Each of our components must be wrapped in this component.
+  It provides the `lapis` prop, which is the URL of the LAPIS server, the server that provides the data for the components. In this example, we are using the LAPIS server for open SARS-CoV-2 data.
+- `gs-location-filter`: This is an example of our input components, which are used to create LAPIS filters for the visualization components. In this case, it is used to filter the data by location.
+- `gs-prevalence-over-time`: This is an example of our visualization components, which are used to visualize the data from the LAPIS server. In this case, it shows the prevalence of a specific variant over time.
+For now, we have provided fixed values for the `numerator`, and `denominator`.
+If you only want to use the visualization components, you are finished here.
+If you want to use the input components, you will need to add some additional code to make them work.
+## Add interactivity between the components
+Each of our `input` components emits an event when the user selects a new value.
+You can listen to this event and update the `visualization` components accordingly.
+In this example, we will use the `gs-location-filter` component to filter the data by location.
+Before we do that, we need to create a state to store the current location. We will use the `useState` hook for this:
+```javascript
+const [location, setLocation] = useState<Record<string, string | undefined>>({
+    region: undefined,
+    country: undefined,
+    division: undefined,
+    location: undefined,
+});
+```
+We then add an event listener to the `gs-location-filter` component to update the `location` state when the user selects a new location:
+```javascript
+import {gsEventNames, LocationChangedEvent} from '@genspectrum/dashboard-components/util';
+// in the Dashboard component
+const locationFilterRef = useRef<HTMLElement>();
+// ...
+useEffect(() => {
+        const locationFilter = locationFilterRef.current;
+        if (!locationFilter) {
+            return;
+        }
+        const handleLocationChange = (event: LocationChangedEvent) => setLocation(event.detail);
+        locationFilter.addEventListener(gsEventNames.locationChanged, handleLocationChange);
+        return () => {
+            locationFilter.removeEventListener(gsEventNames.locationChanged, handleLocationChange);
+        };
+    }, []);
+// ...
+    <gs-location-filter
+        fields='["region", "country", "division", "location"]'
+        placeholderText='Enter a location'
+        ref={locationFilterRef}
+        lapisFilter={JSON.stringify(location)}
+        value={JSON.stringify(location)}
+    ></gs-location-filter>
+```
+As you can see, we provide the `location` state as the `value` prop to the `gs-location-filter` component.
+This allows the component to display the current location and update it when the user selects a new location.
+We also provide the `lapisFilter` prop, which is used in the `gs-location-filter` component itself to provide counts for the selected location on the dropdown.
+In the end, we create the numerator and denominator filters for the `gs-prevalence-over-time` component from the `dateRange` state.
+```javascript
+const denominator = {
+    ...location,
+};
+const numerator = {
+    displayName: 'My variant',
+    lapisFilter: {
+        ...denominator,
+        pangoLineage: 'B.1.1.7*',
+    },
+};
+```
+You can also create a more complex filters, but this will be enough for this example.
+You also might want users to be able to select the variant they want to see. Here it is fixed to `B.1.1.7`.
+Refer to our documentation of our other input components.
+Finally, we use the new variables (`numerator`, `denominator`) in the components:
+```javascript
+return (
+    <gs-app lapis='https://lapis.cov-spectrum.org/open/v2/'>
+        <h2>Filter By Location</h2>
+        <gs-location-filter
+            fields='["region", "country", "division", "location"]'
+            placeholderText='Enter a location'
+            ref={locationFilterRef}
+            lapisFilter={JSON.stringify(location)}
+            value={JSON.stringify(location)}
+        ></gs-location-filter>
+        <h2>Prevalence over time</h2>
+        <gs-prevalence-over-time
+            numeratorFilters={JSON.stringify([numerator])}
+            denominatorFilter={JSON.stringify(denominator)}
+            lapisDateField='date'
+            granularity='day'
+            smoothingWindow='7'
+            views='["line", "table"]'
+        ></gs-prevalence-over-time>
+    </gs-app>
+);
+```

package/src/web-components/visualization/gs-mutations.tsx CHANGED Viewed

@@ -153,7 +153,7 @@ export class MutationsComponent extends PreactLitAdapterWithGridJsStyles {
 declare global {
     interface HTMLElementTagNameMap {
-        'gs-mutations-component': MutationsComponent;
+        'gs-mutations': MutationsComponent;
     }
 }
@@ -161,7 +161,7 @@ declare global {
     // eslint-disable-next-line @typescript-eslint/no-namespace
     namespace JSX {
         interface IntrinsicElements {
-            'gs-mutations-component': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+            'gs-mutations': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
         }
     }
 }

package/src/web-components/visualization/introduction.mdx ADDED Viewed

@@ -0,0 +1,51 @@
+import { Meta } from '@storybook/blocks';
+<Meta title='Visualization/Introduction' />
+# Introduction
+The components in this section visualize data from LAPIS.
+They take a LAPIS filter as input, fetch data from LAPIS and visualize the results in charts and tables.
+Refer to the Swagger UI / OpenAPI documentation of your LAPIS instance for the details of what valid LAPIS filters are.
+The LAPIS filter should only contain actual "query filters"
+(i.e. the LAPIS filter should not include request parameters such as `fields`, `limit`, `orderBy`).
+The components perform minor modifications to the LAPIS filter before sending it to LAPIS,
+such as adding stratification by adding which `fields` the query should return
+or decomposing the filters into multiple filters for smaller time intervals.
+Otherwise, the LAPIS filter is passed to LAPIS unchanged.
+## Preventing Layout Shifts
+While the data is loaded, components don't know how much space they will take up.
+If you didn't set a fixed height, the component will initially be very small as long as it displays a loading spinner.
+Once the data is loaded, users will see a layout shift because the component will grow to its final size.
+All visualization components fire a `gs-component-finished-loading` event when the data is loaded
+and the component is ready to be displayed.
+After a component fired the event, you can expect that there are no more layout shifts.
+To prevent layout shifts, you could initially hide the component and only display it after the event was fired.
+## Data Visualization and Statistical Analysis
+### Scales
+On most plots, users can select the y-axis scaling through a dropdown.
+They can choose between linear, logarithmic and logistic scaling.
+By default, the y-axis is set to a linear scale.
+In general, for each scale the displayed height of a value is calculated by applying the corresponding scale function.
+- Linear: `value`
+- Logarithmic: `ln(value)`
+- Logistic: `ln(value / (1 - value))`
+### Confidence Intervals
+On bar and line plots, users can choose to display confidence intervals.
+For line plots, this is done by shading the area between the upper and lower bounds.
+For bar plots, this is done by adding error bars to the top of each bar.
+Currently, only one method is available for calculating the confidence intervals:
+the [wilson score interval](https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval) with a confidence level of 95%.