visualifyjs 2.5.3 → 3.0.0

package/docs/docs/components/scatterL.md

@@ -1,70 +1,171 @@
-# ScatterL Components
-
-The ScatterL component is a scatter plot that is used to visualize the data in
-2D. It is a part of the Plotly library and is used to visualize the data in 2D.
-The ScatterL component is used to visualize the data in 2D.
-
-The ScatterL component is designed for a specified data Format, like R-tree, to
-visualize a large data set in 2D.
-
-## Requirements
-
-The ScatterL component requires the specified API to fetch the data. Currently,
-the ScatterL component supports the API for fetching the data - in the format of
-JSON, - and it need API to consist as
-`your-backend-server-url/xxx/<x-min>/<y-min>/<x-max>/<y-max>`
-
-We will provide an example of the backend to show you how to implement our
-customized Rtree API.
-
-## Properties
-
-The ScatterL component has the following properties:
-
--   `type` (string): The type of the component, in this case `ScatterL`.
--   `id` (string): The unique identifier of the component.
--   `row` (int): The row in which the component is to be displayed.
--   `col` (int): The column in which the component is to be displayed.
--   `rowspan` (int): The number of rows the component is to span.
--   `config` (object): The configuration of the component.
-
-### config Properties
-
-The `config` object has the following properties:
-
--   `merge` (boolean): Whether to merge the data or not.
--   `startup_msg` (string): The message to be displayed when the component is
-    started.
--   `size` (object): The size of the component.
-    -   `width` (int): The width of the component.
-    -   `height` (int): The height of the component.
-    -   `dotsize` (object): The size of the dots in the scatter plot.
-    -   `dotFactor` (int): The factor by which the dot size is to be multiplied.
-        -   `min` (int): The minimum size of the dot.
-        -   `max` (int): The maximum size of the dot.
-    -   `colourby` (string): The property by which the dots are to be coloured.
-    -   `exclusion` (array): The properties to be excluded.
-    -   `api` (object): The API to be used to fetch the data.
-        -   `metadata` (object): The metadata API.
-            -   `href` (string): The URL of the metadata API.
-            -   `val` (string): The value of the metadata API.
-        -   `gene` (object): The gene API.
-            -   `href` (string): The URL of the gene API.
-            -   `val` (string): The value of the gene API.
-            -   `dep` (string): The dependent property of the gene API.
-    -   `mapping` (object): The mapping of the data.
-        -   `api` (object): The API to be used for mapping.
-            -   Example:
-                -   `ENS (S): 'ens_iter_2'` (string): Maps ENS (S) to endo_iter_2 API.
-                -   `IM (S): 'im_iter_2'` (string): Maps IM (S) to im_iter_2 API.
-                -   `MES (S): 'mes_iter_2'` (string): Maps MES (S) to mes_iter_2 API.
-        -   `axis` (object): The axis to be used for mapping.
-            -   `x: X_Coord` (string):  Maps x-axis to specified value name.
-            -   `y: Y_Coord` (string): Maps y-axis to specified value name.
-            -   `extra` (object): The extra properties.
-                -   Example:
-                    -   `Stage : Stage` (string): Mapes the Stage to the stage property.
-                    -   `MT : MT` (string): Maps the MT to the MT property.
-                    -   `Gene : Gene` (string): Maps the Gene to the gene property.
-                    -   `Cell_Type : Cell_Type` (string): Maps the Cell_Type to the cell type property.
-                    -   `Cell_ID : Cell_ID` (string): Maps the Cell_ID to the cell ID property.
+# ScatterL Component
+
+ScatterL is a high-performance 2D scatter plot built on Plotly, optimized for large datasets using R-tree spatial indexing. It supports viewport-based data loading, meaning only visible data points are fetched from the backend. This makes it suitable for datasets with millions of points where loading everything at once would be impractical.
+
+> **Note:** ScatterL requires a backend API and cannot be used as an inline docsify component. See [MmTrBC](https://visualify.pharmacy.arizona.edu/MmTrBC/) for a live example.
+
+## How It Works
+
+ScatterL uses a viewport-based loading strategy. As the user pans and zooms, the component calculates the visible coordinate range and requests only the data points within that region from the backend API.
+
+```
+┌──────────────────────────────────┐
+│          Full Dataset            │
+│  ┌────────────────┐              │
+│  │   Viewport     │  Only this   │
+│  │   (visible)    │  region is   │
+│  │                │  loaded via  │
+│  │  ● ● ●  ●     │  API call    │
+│  │    ●   ●  ●    │              │
+│  └────────────────┘              │
+│         ●    ●         ●         │
+│    ●        ●    ●               │
+└──────────────────────────────────┘
+API: /api/<x-min>/<y-min>/<x-max>/<y-max>
+```
+
+**Loading flow:**
+
+1. The component renders with an initial viewport.
+2. On pan/zoom, the new bounding box coordinates are computed.
+3. A request is sent to the R-tree API with the bounding box: `<x-min>/<y-min>/<x-max>/<y-max>`.
+4. The API returns only the data points within that region.
+5. The scatter plot updates with the new data.
+
+## Properties
+
+### Top-Level Properties
+
+| Property   | Type     | Required | Description                                        |
+|------------|----------|----------|----------------------------------------------------|
+| `type`     | string   | Yes      | Must be `"ScatterL"`.                              |
+| `id`       | string   | Yes      | Unique identifier for the component.               |
+| `row`      | int      | Yes      | Grid row position for layout.                      |
+| `col`      | int      | Yes      | Grid column position for layout.                   |
+| `rowspan`  | int      | No       | Number of rows the component spans.                |
+| `config`   | object   | Yes      | Configuration object (see below).                  |
+
+### Config Properties
+
+| Property       | Type     | Required | Description                                                    |
+|----------------|----------|----------|----------------------------------------------------------------|
+| `merge`        | boolean  | No       | Whether to merge data from multiple API responses.             |
+| `startup_msg`  | string   | No       | Message displayed while the component initializes.             |
+| `size`         | object   | No       | Dimensions of the component (see Size below).                  |
+| `colourby`     | string   | No       | Property name used to colour the data points.                  |
+| `exclusion`    | array    | No       | List of property names to exclude from display.                |
+| `api`          | object   | Yes      | API endpoints for data fetching (see API below).               |
+| `mapping`      | object   | Yes      | Data mapping configuration (see Mapping below).                |
+
+### Size Properties
+
+| Property    | Type   | Description                                       |
+|-------------|--------|---------------------------------------------------|
+| `width`     | int    | Width of the component in pixels.                 |
+| `height`    | int    | Height of the component in pixels.                |
+| `dotsize`   | object | Controls dot rendering size.                      |
+| `dotFactor` | int    | Multiplier applied to dot size.                   |
+| `min`       | int    | Minimum dot size in pixels.                       |
+| `max`       | int    | Maximum dot size in pixels.                       |
+
+### API Properties
+
+| Property         | Type   | Description                                                         |
+|------------------|--------|---------------------------------------------------------------------|
+| `api.metadata`   | object | Metadata endpoint configuration.                                    |
+| `metadata.href`  | string | URL of the metadata API.                                            |
+| `metadata.val`   | string | Variable name used to reference the metadata.                       |
+| `api.gene`       | object | Gene expression endpoint configuration.                             |
+| `gene.href`      | string | URL of the gene API.                                                |
+| `gene.val`       | string | Variable name used to reference the gene data.                      |
+| `gene.dep`       | string | Dependent property that triggers gene data loading.                 |
+
+### Mapping Properties
+
+| Property        | Type   | Description                                                                |
+|-----------------|--------|----------------------------------------------------------------------------|
+| `mapping.api`   | object | Maps display labels to R-tree API endpoint names.                          |
+| `mapping.axis`  | object | Maps axis identifiers to data property names.                              |
+| `axis.x`        | string | Data property name mapped to the x-axis (e.g., `"X_Coord"`).             |
+| `axis.y`        | string | Data property name mapped to the y-axis (e.g., `"Y_Coord"`).             |
+| `axis.extra`    | object | Additional data properties to include (key-value pairs of label to name). |
+
+## API Requirements
+
+ScatterL expects a backend API that serves data using R-tree spatial indexing. The API must accept bounding box coordinates in the URL path:
+
+```
+<base-url>/<endpoint>/<x-min>/<y-min>/<x-max>/<y-max>
+```
+
+**Response format:** The API should return a JSON object containing arrays for each mapped property. For example:
+
+```json
+{
+  "X_Coord": [1.2, 3.4, 5.6],
+  "Y_Coord": [7.8, 9.0, 1.1],
+  "Cell_Type": ["TypeA", "TypeB", "TypeA"],
+  "Gene": [0.5, 1.2, 0.8]
+}
+```
+
+The `mapping.api` object maps user-facing labels to specific R-tree endpoints. Each endpoint returns data for a particular subset or iteration of the dataset.
+
+## Example
+
+```json
+{
+  "id": "scatter_large",
+  "type": "ScatterL",
+  "row": 1,
+  "col": 1,
+  "rowspan": 3,
+  "config": {
+    "merge": false,
+    "startup_msg": "Loading scatter plot...",
+    "size": {
+      "width": 800,
+      "height": 600,
+      "dotsize": { "min": 2, "max": 10 },
+      "dotFactor": 1
+    },
+    "colourby": "Cell_Type",
+    "exclusion": ["Cell_ID"],
+    "api": {
+      "metadata": {
+        "href": "https://your-api.example.com/metadata",
+        "val": "scatter_meta"
+      },
+      "gene": {
+        "href": "https://your-api.example.com/gene",
+        "val": "scatter_gene",
+        "dep": "Gene"
+      }
+    },
+    "mapping": {
+      "api": {
+        "ENS (S)": "ens_iter_2",
+        "IM (S)": "im_iter_2",
+        "MES (S)": "mes_iter_2"
+      },
+      "axis": {
+        "x": "X_Coord",
+        "y": "Y_Coord",
+        "extra": {
+          "Stage": "Stage",
+          "MT": "MT",
+          "Gene": "Gene",
+          "Cell_Type": "Cell_Type",
+          "Cell_ID": "Cell_ID"
+        }
+      }
+    }
+  }
+}
+```
+
+## See Also
+
+- [MmTrBC Showcase](https://visualify.pharmacy.arizona.edu/MmTrBC/) -- live example using ScatterL with R-tree spatial indexing
+- [Visium Component](/components/visium.md) -- spatial transcriptomics visualization with image overlay
+- [Plotly Component](/components/plotly.md) -- general-purpose Plotly charts in page mode

package/docs/docs/components/visium.md

@@ -1,57 +1,112 @@
-# Visium Component
-
-The Visium component is used to display the Visium data on the page.
-
-## Properties
-
-The Visium component has the following properties:
-
--   `type` (string): The type of the component, in this case `Visium`.
--   `id` (string): The unique identifier of the component.
--   `row` (int): The row in which the component is to be displayed.
--   `col` (int): The column in which the component is to be displayed.
--   `rowspan` (int): The number of rows the component is to span.
--   `startup_msg` (string): The startup message of the component.
--   `meta` (string): The metadata API of the component.
--   `simpleload` (boolean): Whether to load the data simply or not.
--   `metaval` (string): The metadata variable name we want to use.
--   `gene` (string): The gene API.
--   `geneval` (string): The gene variable name we want to use.
--   `image` (string): The image API.
--   `cellval` (string): The celltype variable name we want to use.
--   `axis_mapping` (object): The axis mapping of the component.
-    -   `x: X_Coord` (string): Maps the X_Coord to the x-axis.
-    -   `y: Y_Coord` (string): Maps the Y_Coord to the y-axis.
-    -   `extra` (object): The extra properties.
-        -   Example:
-            -   `BC : BC` (string): Maps the BC to the BC property.
-            -   `SB-1 : SB-1` (string): Maps the SB-1 to the SB-1 property.
-
-
-### Example
-
-```json
-        {
-            "id": "visium_scatter2d",
-            "type": "Visium",
-            "row": 1,
-            "col": 2,
-            "rowspan": 3,
-            "startup_msg": "Section",
-            "meta": "<your-api-for-metadata>",
-            "simpleload": false,
-            "metaval": "visium_section",
-            "gene": "<your-api-for-gene-data>",
-            "geneval": "visium_gene",
-            "image": "<your-api-for-image>",
-            "cellval": "visium_celltype",
-            "axis_mapping": {
-                "x": "X_Coord",
-                "y": "Y_Coord",
-                "extra": {
-                    "BC": "BC",
-                    "SB-1": "SB-1",
-                }
-            }
-        }
-```
+# Visium Component
+
+The Visium component visualizes spatial transcriptomics data from the 10x Genomics Visium platform. It overlays gene expression data on tissue section images, allowing researchers to explore spatial patterns of gene expression. Each spot on the tissue is rendered as a colored dot, where the color represents either gene expression levels or cell type annotations.
+
+> **Note:** Visium requires backend APIs for metadata, gene expression, and tissue images. It cannot be used as an inline docsify component. See [EsoDev](https://visualify.pharmacy.arizona.edu/EsoDev/) for a live example.
+
+## How It Works
+
+The Visium component combines three data sources to produce a spatial overlay visualization:
+
+```
+┌─────────────────────────────────────┐
+│         Tissue Section Image         │
+│                                      │
+│    ●(red)  ●(blue)   ●(green)       │
+│        ●(yellow)  ●(blue)            │
+│    ●(green)     ●(red)   ●(blue)    │
+│                                      │
+│  Spots colored by gene expression    │
+│  or cell type annotation             │
+└─────────────────────────────────────┘
+
+Data Sources:
+  metadata API → cell annotations
+  gene API     → expression values
+  image API    → tissue image
+```
+
+**Rendering flow:**
+
+1. The tissue section image is loaded from the image API and displayed as the background.
+2. Cell metadata (annotations, barcodes, coordinates) is fetched from the metadata API.
+3. Spots are plotted at their spatial coordinates on top of the tissue image.
+4. When a gene is selected, expression values are fetched from the gene API and used to colour the spots.
+5. Users can switch between colouring by cell type annotation or gene expression.
+
+## Properties
+
+| Property       | Type     | Required | Description                                                                 |
+|----------------|----------|----------|-----------------------------------------------------------------------------|
+| `type`         | string   | Yes      | Must be `"Visium"`.                                                         |
+| `id`           | string   | Yes      | Unique identifier for the component.                                        |
+| `row`          | int      | Yes      | Grid row position for layout.                                               |
+| `col`          | int      | Yes      | Grid column position for layout.                                            |
+| `rowspan`      | int      | No       | Number of rows the component spans.                                         |
+| `startup_msg`  | string   | No       | Message displayed while the component initializes.                          |
+| `meta`         | string   | Yes      | URL of the metadata API endpoint.                                           |
+| `metaval`      | string   | Yes      | Variable name used to reference the metadata.                               |
+| `gene`         | string   | Yes      | URL of the gene expression API endpoint.                                    |
+| `geneval`      | string   | Yes      | Variable name used to reference the gene data.                              |
+| `image`        | string   | Yes      | URL of the tissue section image API endpoint.                               |
+| `cellval`      | string   | Yes      | Variable name used to reference cell type annotations.                      |
+| `simpleload`   | boolean  | No       | When `true`, loads all data at once. When `false`, uses incremental loading.|
+| `axis_mapping` | object   | Yes      | Maps data properties to axes and extra display fields (see below).          |
+
+### Axis Mapping Properties
+
+| Property          | Type   | Description                                                          |
+|-------------------|--------|----------------------------------------------------------------------|
+| `axis_mapping.x`  | string | Data property name mapped to the x-axis (e.g., `"X_Coord"`).       |
+| `axis_mapping.y`  | string | Data property name mapped to the y-axis (e.g., `"Y_Coord"`).       |
+| `axis_mapping.extra` | object | Additional data properties to display. Key-value pairs where the key is the display label and the value is the property name in the data. |
+
+## Example
+
+```json
+{
+  "id": "visium_scatter2d",
+  "type": "Visium",
+  "row": 1,
+  "col": 2,
+  "rowspan": 3,
+
+  // Message shown during initial load
+  "startup_msg": "Section",
+
+  // Metadata API: provides cell annotations and coordinates
+  "meta": "https://your-api.example.com/metadata",
+  "metaval": "visium_section",
+
+  // Gene expression API: provides per-spot expression values
+  "gene": "https://your-api.example.com/gene",
+  "geneval": "visium_gene",
+
+  // Tissue image API: serves the H&E stained tissue image
+  "image": "https://your-api.example.com/tissue-image",
+
+  // Cell type variable name for annotation colouring
+  "cellval": "visium_celltype",
+
+  // Load data incrementally (false) or all at once (true)
+  "simpleload": false,
+
+  // Map data properties to axes and tooltip fields
+  "axis_mapping": {
+    "x": "X_Coord",
+    "y": "Y_Coord",
+    "extra": {
+      "BC": "BC",
+      "SB-1": "SB-1"
+    }
+  }
+}
+```
+
+> **Note:** JSON does not support comments. The comments above are included for explanation only. Remove them in your actual configuration.
+
+## See Also
+
+- [EsoDev Showcase](https://visualify.pharmacy.arizona.edu/EsoDev/) -- live example using the Visium component
+- [ScatterL Component](/components/scatterL.md) -- high-performance scatter plot with R-tree spatial indexing
+- [DotBio Component](/components/dotBio.md) -- another biology-focused visualization component