precision-dashwidgets 0.5.1 → 0.5.3

package/README.md

@@ -1,5 +1,415 @@
-# Vue 3 + TypeScript + Vite
+# precision-dashwidgets
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+Interactive genomics visualization widgets built with Vue 3. These components provide gene expression analysis, dimensionality reduction plots (UMAP/tSNE), and distribution visualizations powered by DuckDB WASM for client-side querying of Parquet data files.
 
-Learn more about the recommended Project Setup and IDE Support in the [Vue Docs TypeScript Guide](https://vuejs.org/guide/typescript/overview.html#project-setup).
+## Components
+
+### GeneExpression
+
+Gene co-expression analysis widget. Renders a scatter plot (UMAP or tSNE) colored by the co-expression of two selected genes. Includes autocomplete gene search, dual gene selection, and a statistics panel.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `dataPath` | `string?` | URL to data directory containing Parquet files. Falls back to injected `s3Url`, then the default. |
+| `initialGene1` | `string?` | Pre-selected first gene (e.g. `"CDH9"`) |
+| `initialGene2` | `string?` | Pre-selected second gene (e.g. `"TAC1"`) |
+
+### SideBySide
+
+Dual-panel comparison widget. Left panel shows a UMAP colored by a selected metadata column (cell type, cluster, etc.). Right panel shows a UMAP colored by expression level of a selected gene. Useful for comparing spatial clustering against gene expression patterns.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `dataPath` | `string?` | URL to data directory containing Parquet files. Falls back to injected `s3Url`, then the default. |
+| `initialGene` | `string?` | Pre-selected gene for the expression panel |
+| `initialMetadataColumn` | `string?` | Pre-selected metadata column for the metadata panel |
+
+### ViolinPlot (also exported as `GeneXDistribution`)
+
+Gene expression distribution widget. Renders violin or box plots showing the distribution of a gene's expression across metadata categories. Supports toggling between violin and box plot modes, and can overlay individual data points.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `dataPath` | `string?` | URL to data directory containing Parquet files. Falls back to injected `s3Url`, then the default. |
+| `initialGene` | `string?` | Pre-selected gene |
+| `initialMetadataColumn` | `string?` | Pre-selected metadata column for x-axis grouping |
+
+### Additional Components
+
+- **DataExplorer** - Data exploration interface
+- **UMAP** - Standalone UMAP visualization
+- **ProportionPlot** - Cell proportion visualization
+
+## Data Requirements
+
+All components use DuckDB WASM to query Parquet files from a remote data path (S3 or any HTTP-accessible location). The data path must contain the following files:
+
+| File | Required | Description |
+|------|----------|-------------|
+| `umap_complete.parquet` | Yes | UMAP coordinates + cell metadata |
+| `tsne_complete.parquet` | No | tSNE coordinates (enables tSNE option in GeneExpression) |
+| `gene_locations.parquet` | Yes | Mapping of gene names to their data file locations |
+| `gene_stats.parquet` | Yes | Gene-level statistics used for search/autocomplete |
+| `cells.parquet` | Yes | Cell metadata (cell types, clusters, etc.) |
+| `metadata.parquet` | No | Alternative/extended metadata source |
+| `genes.parquet` | Yes | Gene name to ID mapping |
+
+Gene expression values are loaded on-demand from individual or chunked Parquet files referenced in `gene_locations.parquet`.
+
+---
+
+## Use Case 1: Inside the Pennsieve Dashboard
+
+When used within the `pennsieve-dashboard`, components are provided context automatically via Vue's `provide`/`inject` and a shared Pinia store.
+
+### Install
+
+The package is already a workspace dependency. If needed:
+
+```bash
+npm install precision-dashwidgets
+```
+
+### Import Components
+
+```js
+import {
+  GeneExpression,
+  SideBySide,
+  ViolinPlot, // or GeneXDistribution
+} from 'precision-dashwidgets'
+import 'precision-dashwidgets/style.css'
+```
+
+### Register in a Layout
+
+The dashboard uses a widget layout system. Register components in your layout config:
+
+```js
+const defaultLayout = [
+  {
+    id: 'GeneExpression-0',
+    x: 0, y: 0, w: 3, h: 8,
+    componentKey: 'GeneExpression',
+    componentName: 'Gene Co-expression',
+    component: GeneExpression,
+    Props: {
+      initialGene1: 'CDH9',
+      initialGene2: 'TAC1',
+    },
+  },
+  {
+    id: 'SideBySide-0',
+    x: 3, y: 0, w: 3, h: 8,
+    componentKey: 'SideBySide',
+    componentName: 'Side by Side',
+    component: SideBySide,
+    Props: {
+      initialGene: 'CDH9',
+      initialMetadataColumn: 'cell_type',
+    },
+  },
+  {
+    id: 'ViolinPlot-0',
+    x: 0, y: 8, w: 3, h: 8,
+    componentKey: 'ViolinPlot',
+    componentName: 'Gene Distribution',
+    component: ViolinPlot,
+    Props: {
+      initialGene: 'CDH9',
+      initialMetadataColumn: 'cell_type',
+    },
+  },
+]
+```
+
+### How State Flows in the Dashboard
+
+The dashboard provides two context mechanisms:
+
+1. **Global vars injection** (`DASHBOARD_GLOBAL_VARS_KEY`) - provides `s3Url`, `apiUrl`, and shared filters via `provide`/`inject`.
+2. **Pinia store** (`usePrecisionStore`) - shared reactive state for gene and metadata selections across all widgets. When a user selects a gene in one widget, other widgets can react.
+
+These are wired automatically when used inside the dashboard framework.
+
+---
+
+## Use Case 2: Standalone (Without Pennsieve Dashboard)
+
+You can use these components in any Vue 3 application. This requires setting up the dependencies that the dashboard normally provides.
+
+### Install
+
+```bash
+npm install precision-dashwidgets
+```
+
+### Peer Dependencies
+
+Install the required peer dependencies:
+
+```bash
+npm install vue pinia element-plus @element-plus/icons-vue
+```
+
+### Setup
+
+#### 1. Register Pinia and Element Plus
+
+```js
+// main.ts
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import ElementPlus from 'element-plus'
+import 'element-plus/dist/index.css'
+import App from './App.vue'
+
+const app = createApp(App)
+app.use(createPinia())
+app.use(ElementPlus)
+app.mount('#app')
+```
+
+#### 2. Import Styles
+
+```js
+import 'precision-dashwidgets/style.css'
+```
+
+#### 3. Use the Components
+
+The simplest approach is to pass your data URL directly via the `dataPath` prop. Your directory must contain the same Parquet file names listed in [Data Requirements](#data-requirements).
+
+```vue
+<template>
+  <div style="height: 600px; width: 100%;">
+    <GeneExpression
+      dataPath="https://your-bucket.s3.amazonaws.com/your-dataset"
+      initialGene1="CDH9"
+      initialGene2="TAC1"
+    />
+  </div>
+
+  <div style="height: 600px; width: 100%;">
+    <SideBySide
+      dataPath="https://your-bucket.s3.amazonaws.com/your-dataset"
+      initialGene="CDH9"
+      initialMetadataColumn="cell_type"
+    />
+  </div>
+
+  <div style="height: 500px; width: 100%;">
+    <ViolinPlot
+      dataPath="https://your-bucket.s3.amazonaws.com/your-dataset"
+      initialGene="CDH9"
+      initialMetadataColumn="cell_type"
+    />
+  </div>
+</template>
+
+<script setup>
+import {
+  GeneExpression,
+  SideBySide,
+  ViolinPlot,
+} from 'precision-dashwidgets'
+</script>
+```
+
+#### Alternative: Provide Global Vars (set data path once)
+
+Instead of passing `dataPath` to every component, you can provide `DASHBOARD_GLOBAL_VARS_KEY` in an ancestor component. All widgets will inherit the `s3Url` from it:
+
+```vue
+<script setup>
+import { provide, ref } from 'vue'
+import { DASHBOARD_GLOBAL_VARS_KEY } from 'precision-dashwidgets'
+
+provide(DASHBOARD_GLOBAL_VARS_KEY, {
+  s3Url: ref('https://your-bucket.s3.amazonaws.com/your-dataset'),
+  apiUrl: ref(''),
+  filters: ref({}),
+  setFilter: () => {},
+  clearFilter: () => {},
+})
+</script>
+```
+
+**Resolution order:** `dataPath` prop > injected `s3Url` > built-in default URL.
+
+### Accessing Shared State
+
+If you need to read or control widget selections programmatically, import the Pinia store:
+
+```js
+import { usePrecisionStore } from 'precision-dashwidgets'
+
+const store = usePrecisionStore()
+
+// Read current selections
+console.log(store.selectedGene)
+console.log(store.selectedMetadataColumn)
+
+// Set selections programmatically
+store.setSelectedGene('TAC1')
+store.setSelectedMetadataColumn('cluster')
+```
+
+#### Store Properties
+
+| Property | Used By | Description |
+|----------|---------|-------------|
+| `selectedGene` | SideBySide | Currently selected gene |
+| `selectedMetadataColumn` | SideBySide, ViolinPlot | Currently selected metadata column |
+| `selectedGene1` | GeneExpression | First gene in co-expression |
+| `selectedGene2` | GeneExpression | Second gene in co-expression |
+| `selectedGeneX` | ViolinPlot | Selected gene for distribution plot |
+
+---
+
+## Exports
+
+```js
+// Components
+export { GeneExpression }       // Gene co-expression analysis
+export { SideBySide }           // Dual UMAP comparison
+export { ViolinPlot }           // Violin/box plot (alias for GeneXDistribution)
+export { GeneXDistribution }    // Violin/box plot (original name)
+export { DataExplorer }         // Data exploration
+export { UMAP }                 // Standalone UMAP
+export { ProportionPlot }       // Proportion visualization
+
+// Utilities
+export { usePrecisionStore }          // Pinia store for shared widget state
+export { useDashboardGlobalVars }     // Composable to access injected global vars
+export { DASHBOARD_GLOBAL_VARS_KEY }  // Injection key for providing global vars
+```
+
+## Bringing Your Own Data
+
+You can point the widgets at any HTTP-accessible directory, as long as it contains Parquet files with the **exact names** listed in [Data Requirements](#data-requirements). The internal `dataManager` appends those filenames to whatever base path you provide (e.g. `{dataPath}/umap_complete.parquet`).
+
+Currently there is no way to customize file names, column mappings, or the data schema. See the roadmap below for planned support.
+
+## Known Limitations
+
+- **Fixed Parquet file names**: Your data directory must use the exact file names the `dataManager` expects (`umap_complete.parquet`, `genes.parquet`, etc.). Custom naming is not yet supported.
+- **Fixed column schema**: The components expect specific column names inside the Parquet files (e.g. UMAP coordinates, gene expression values). These cannot be remapped yet.
+- **DuckDB WASM**: Components initialize a DuckDB WASM instance at mount time, which downloads the DuckDB worker from jsDelivr CDN. Ensure your environment allows loading scripts from `cdn.jsdelivr.net`.
+- **Sizing**: Components expand to fill their parent container. Wrap them in a container with explicit `height` and `width`.
+- **One DuckDB instance per component**: Each widget creates its own `UMAPGeneViewer` / DuckDB instance. If you mount multiple widgets, they each load data independently.
+
+---
+
+## Roadmap: Configurable Data Schema
+
+Currently the `dataManager` has hardcoded file names and column expectations. The plan for making this fully configurable:
+
+### Phase 1 - Data Config Object
+
+Introduce a `DataConfig` type that maps logical data roles to actual file paths and column names:
+
+```ts
+interface DataConfig {
+  // Base URL for all data files
+  basePath: string
+
+  // File name overrides (defaults to current names)
+  files: {
+    umap?: string           // default: "umap_complete.parquet"
+    tsne?: string           // default: "tsne_complete.parquet"
+    geneLocations?: string  // default: "gene_locations.parquet"
+    geneStats?: string      // default: "gene_stats.parquet"
+    cells?: string          // default: "cells.parquet"
+    metadata?: string       // default: "metadata.parquet"
+    genes?: string          // default: "genes.parquet"
+  }
+
+  // Column name mappings per file
+  columns: {
+    umap?: {
+      x?: string            // default: "umap_1"
+      y?: string            // default: "umap_2"
+      cellId?: string       // default: "cell_id"
+    }
+    tsne?: {
+      x?: string            // default: "tsne_1"
+      y?: string            // default: "tsne_2"
+    }
+    genes?: {
+      name?: string         // default: "gene_name"
+      id?: string           // default: "gene_id"
+    }
+    // ... etc for each file
+  }
+}
+```
+
+### Phase 2 - Update dataManager.js
+
+Refactor `UMAPGeneViewer` to accept a `DataConfig` instead of a plain `basePath` string:
+
+1. `loadEssentialData()` reads file paths from `config.files` instead of hardcoded names.
+2. All SQL queries use `config.columns` mappings instead of hardcoded column names.
+3. Merge user-provided config with defaults so only overrides need to be specified.
+
+### Phase 3 - Shared DuckDB Instance
+
+Instead of each component creating its own DuckDB instance:
+
+1. Create a `useDataManager()` composable that provides a singleton `UMAPGeneViewer` via `provide`/`inject`.
+2. Components call `useDataManager()` to get the shared instance.
+3. The config is set once at the provider level, all widgets share the connection and cache.
+
+### Phase 4 - Component Props
+
+Wire the config through the component layer:
+
+1. Wrapper components accept an optional `dataConfig` prop.
+2. If not provided, fall back to the injected shared instance.
+3. The `provide` approach from Phase 3 becomes the recommended setup for standalone users.
+
+This would let standalone users do:
+
+```vue
+<script setup>
+import { provide } from 'vue'
+import { createDataProvider } from 'precision-dashwidgets'
+
+const dataProvider = createDataProvider({
+  basePath: 'https://my-bucket.s3.amazonaws.com/my-data',
+  files: {
+    umap: 'embeddings.parquet',
+    genes: 'gene_index.parquet',
+  },
+  columns: {
+    umap: { x: 'dim1', y: 'dim2' },
+  },
+})
+
+provide('precision:data', dataProvider)
+</script>
+```
+
+## Development
+
+```bash
+# Start dev server
+npm run dev
+
+# Build library
+npm run build
+
+# Preview build
+npm run preview
+```
+
+## Tech Stack
+
+- **Vue 3** - Component framework
+- **DuckDB WASM** - Client-side SQL engine for Parquet file queries
+- **D3.js** - SVG-based visualizations (violin plots, axes, legends)
+- **regl** - WebGL rendering for high-performance scatter plots
+- **Pinia** - State management across widgets
+- **Element Plus** - UI components (dropdowns, inputs)
+- **Vite** - Build tooling (library mode)

package/dist/{deflate-BQVLA3Ul.mjs → deflate-CPNmBnej.mjs}

@@ -1,5 +1,5 @@
 import { i as r } from "./pako.esm-D_m2s4NW.mjs";
-import { B as a } from "./index-BHHg5z03.mjs";
+import { B as a } from "./index-DVfUy50r.mjs";
 class s extends a {
   decodeBlock(e) {
     return r(new Uint8Array(e)).buffer;

package/dist/index-CRAkqt4--BsX7X3Wy.mjs

@@ -0,0 +1,4 @@
+import { a as r } from "./index-Dl_ufo4v.mjs";
+export {
+  r as TextViewer
+};

package/dist/{index-BHHg5z03.mjs → index-DVfUy50r.mjs}

@@ -2,7 +2,7 @@ var Ky = Object.defineProperty;
 var Oy = (t, A, e) => A in t ? Ky(t, A, { enumerable: !0, configurable: !0, writable: !0, value: e }) : t[A] = e;
 var f = (t, A, e) => Oy(t, typeof A != "symbol" ? A + "" : A, e);
 import { defineComponent as pC, ref as ee, watch as jI, onMounted as Hf, onUnmounted as Yf, openBlock as Ne, createElementBlock as ve, unref as Bo, createElementVNode as _A, createCommentVNode as vt, toDisplayString as Mo, Fragment as Wy, createVNode as Vy, nextTick as zy, normalizeStyle as Xy, computed as ll, createTextVNode as El, normalizeClass as jy } from "vue";
-import { g as Zy } from "./index-Hx8PFhs9.mjs";
+import { g as Zy } from "./index-Dl_ufo4v.mjs";
 function sa(t, A) {
   if (!t)
     throw new Error(A || "loader assertion failed.");
@@ -28949,19 +28949,19 @@ const U0 = {
 function Ht(t, A) {
   Array.isArray(t) || (t = [t]), t.forEach((e) => Jk.set(e, A));
 }
-Ht([void 0, 1], () => import("./raw-KFPBw5cQ.mjs").then((t) => t.default));
-Ht(5, () => import("./lzw-u9cBMr9g.mjs").then((t) => t.default));
+Ht([void 0, 1], () => import("./raw-CommQb0l.mjs").then((t) => t.default));
+Ht(5, () => import("./lzw-Bh2N3zBo.mjs").then((t) => t.default));
 Ht(6, () => {
   throw new Error("old style JPEG compression is not supported.");
 });
-Ht(7, () => import("./jpeg-l5M1J8Gh.mjs").then((t) => t.default));
-Ht([8, 32946], () => import("./deflate-BQVLA3Ul.mjs").then((t) => t.default));
-Ht(32773, () => import("./packbits-dQba4PyI.mjs").then((t) => t.default));
+Ht(7, () => import("./jpeg-CXAyIdl8.mjs").then((t) => t.default));
+Ht([8, 32946], () => import("./deflate-CPNmBnej.mjs").then((t) => t.default));
+Ht(32773, () => import("./packbits-DaRNs4L0.mjs").then((t) => t.default));
 Ht(
   34887,
-  () => import("./lerc-BipMr5R9.mjs").then(async (t) => (await t.zstd.init(), t)).then((t) => t.default)
+  () => import("./lerc-DmIa8s0n.mjs").then(async (t) => (await t.zstd.init(), t)).then((t) => t.default)
 );
-Ht(50001, () => import("./webimage-CBOAIeUr.mjs").then((t) => t.default));
+Ht(50001, () => import("./webimage-BKZpDwde.mjs").then((t) => t.default));
 function Hk(t, A) {
   let e = t.length - A, i = 0;
   do {
@@ -44756,7 +44756,7 @@ Si([8, 32946], () => import("./deflate-DbhbvOaP-D8NSBt31.mjs").then((t) => t.def
 Si(32773, () => import("./packbits-BuzK6gM3-6Um4hupZ.mjs").then((t) => t.default));
 Si(
   34887,
-  () => import("./lerc-XufrP0FH-SNCeY3ab.mjs").then(async (t) => (await t.zstd.init(), t)).then((t) => t.default)
+  () => import("./lerc-XufrP0FH-Cp9B8C70.mjs").then(async (t) => (await t.zstd.init(), t)).then((t) => t.default)
 );
 Si(50001, () => import("./webimage--SJddlky-F_hESl4q.mjs").then((t) => t.default));
 function xg(t, A, e, i = 1) {