openms-insight 0.1.4__tar.gz → 0.1.6__tar.gz

{openms_insight-0.1.4 → openms_insight-0.1.6}/.gitignore

@@ -61,3 +61,4 @@ Thumbs.db
 
 # Logs
 *.log
+CLAUDE.md

{openms_insight-0.1.4 → openms_insight-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openms-insight
-Version: 0.1.4
+Version: 0.1.6
 Summary: Interactive visualization components for mass spectrometry data in Streamlit
 Project-URL: Homepage, https://github.com/t0mdavid-m/OpenMS-Insight
 Project-URL: Documentation, https://github.com/t0mdavid-m/OpenMS-Insight#readme
@@ -50,6 +50,7 @@ Interactive visualization components for mass spectrometry data in Streamlit, ba
 - **Table component** (Tabulator.js) with filtering, sorting, go-to, pagination, CSV export
 - **Line plot component** (Plotly.js) with highlighting, annotations, zoom
 - **Heatmap component** (Plotly scattergl) with multi-resolution downsampling for millions of points
+- **Volcano plot component** for differential expression visualization with significance thresholds
 - **Sequence view component** for peptide visualization with fragment ion matching and auto-zoom
 
 ## Installation
@@ -62,7 +63,7 @@ pip install openms-insight
 
 ```python
 import streamlit as st
-from openms_insight import Table, LinePlot, StateManager
+from openms_insight import Table, LinePlot, Heatmap, VolcanoPlot, StateManager
 
 # Create state manager for cross-component linking
 state_manager = StateManager()
@@ -169,6 +170,21 @@ Table(
 - `pagination`: Enable pagination for large tables (default: True)
 - `page_size`: Rows per page (default: 100)
 
+**Custom formatters:**
+In addition to Tabulator's built-in formatters, these custom formatters are available:
+- `scientific`: Exponential notation (e.g., "1.23e-05") - use `formatterParams: {precision: 3}`
+- `signed`: Explicit +/- prefix (e.g., "+1.234") - use `formatterParams: {precision: 3, showPositive: true}`
+- `badge`: Colored pill/badge for categorical values - use `formatterParams: {colorMap: {"Up": "#FF0000"}, defaultColor: "#888"}`
+
+```python
+column_definitions=[
+    {'field': 'pvalue', 'title': 'P-value', 'formatter': 'scientific', 'formatterParams': {'precision': 2}},
+    {'field': 'log2fc', 'title': 'Log2 FC', 'formatter': 'signed', 'formatterParams': {'precision': 3}},
+    {'field': 'regulation', 'title': 'Status', 'formatter': 'badge',
+     'formatterParams': {'colorMap': {'Up': '#d62728', 'Down': '#1f77b4', 'NS': '#888888'}}},
+]
+```
+
 ### LinePlot
 
 Stick-style line plot using Plotly.js for mass spectra visualization.
@@ -227,6 +243,80 @@ Heatmap(
 - `min_points`: Target size for downsampling (default: 20000)
 - `x_bins`, `y_bins`: Grid resolution for spatial binning
 - `colorscale`: Plotly colorscale name (default: 'Portland')
+- `log_scale`: Use log10 color mapping (default: True). Set to False for linear.
+- `intensity_label`: Custom colorbar label (default: 'Intensity')
+
+**Linear scale example:**
+```python
+Heatmap(
+    cache_id="psm_scores",
+    data_path="psm_data.parquet",
+    x_column='rt',
+    y_column='mz',
+    intensity_column='score',
+    log_scale=False,              # Linear color mapping
+    intensity_label='Score',      # Custom colorbar label
+    colorscale='Blues',
+)
+```
+
+**Categorical mode:**
+Use `category_column` for discrete coloring by category instead of continuous intensity colorscale:
+
+```python
+Heatmap(
+    cache_id="samples_heatmap",
+    data_path="samples.parquet",
+    x_column='retention_time',
+    y_column='mass',
+    intensity_column='intensity',
+    category_column='sample_group',  # Color by category instead of intensity
+    category_colors={                 # Optional custom colors
+        'Control': '#1f77b4',
+        'Treatment_A': '#ff7f0e',
+        'Treatment_B': '#2ca02c',
+    },
+)
+```
+
+### VolcanoPlot
+
+Interactive volcano plot for differential expression analysis with significance thresholds.
+
+```python
+from openms_insight import VolcanoPlot
+
+VolcanoPlot(
+    cache_id="de_volcano",
+    data_path="differential_expression.parquet",
+    log2fc_column='log2FC',
+    pvalue_column='pvalue',
+    label_column='protein_name',       # Optional: labels for significant points
+    filters={'comparison': 'comparison_id'},
+    interactivity={'protein': 'protein_id'},
+    title="Differential Expression",
+    x_label="Log2 Fold Change",
+    y_label="-log10(p-value)",
+    up_color='#d62728',               # Color for up-regulated
+    down_color='#1f77b4',             # Color for down-regulated
+    ns_color='#888888',               # Color for not significant
+)(
+    state_manager=state_manager,
+    fc_threshold=1.0,                  # Fold change threshold (render-time)
+    p_threshold=0.05,                  # P-value threshold (render-time)
+    max_labels=20,                     # Max labels to show
+)
+```
+
+**Key parameters:**
+- `log2fc_column`: Column with log2 fold change values
+- `pvalue_column`: Column with p-values (automatically converted to -log10)
+- `label_column`: Optional column for point labels
+- `up_color`, `down_color`, `ns_color`: Colors for significance categories
+- `fc_threshold`, `p_threshold`: Significance thresholds (passed at render time, not cached)
+- `max_labels`: Maximum number of labels to display on significant points
+
+**Render-time thresholds:** The `fc_threshold` and `p_threshold` are passed via `__call__()`, not `__init__()`. This allows instant threshold adjustment without cache invalidation.
 
 ### SequenceView
 
@@ -290,6 +380,7 @@ All components accept these common arguments:
 | `interactivity` | `Dict[str, str]` | `None` | Map identifier -> column for click actions |
 | `cache_path` | `str` | `"."` | Base directory for cache storage |
 | `regenerate_cache` | `bool` | `False` | Force cache regeneration |
+| `height` | `int` | `400` | Component height in pixels (render-time parameter) |
 
 ## Memory-Efficient Preprocessing
 
@@ -373,6 +464,14 @@ npm run dev
 SVC_DEV_MODE=true SVC_DEV_URL=http://localhost:5173 streamlit run app.py
 ```
 
+### Debug Mode
+
+Enable hash tracking logs to debug data synchronization issues:
+
+```bash
+SVC_DEBUG_HASH=true streamlit run app.py
+```
+
 ### Running Tests
 
 ```bash

{openms_insight-0.1.4 → openms_insight-0.1.6}/README.md

@@ -15,6 +15,7 @@ Interactive visualization components for mass spectrometry data in Streamlit, ba
 - **Table component** (Tabulator.js) with filtering, sorting, go-to, pagination, CSV export
 - **Line plot component** (Plotly.js) with highlighting, annotations, zoom
 - **Heatmap component** (Plotly scattergl) with multi-resolution downsampling for millions of points
+- **Volcano plot component** for differential expression visualization with significance thresholds
 - **Sequence view component** for peptide visualization with fragment ion matching and auto-zoom
 
 ## Installation
@@ -27,7 +28,7 @@ pip install openms-insight
 
 ```python
 import streamlit as st
-from openms_insight import Table, LinePlot, StateManager
+from openms_insight import Table, LinePlot, Heatmap, VolcanoPlot, StateManager
 
 # Create state manager for cross-component linking
 state_manager = StateManager()
@@ -134,6 +135,21 @@ Table(
 - `pagination`: Enable pagination for large tables (default: True)
 - `page_size`: Rows per page (default: 100)
 
+**Custom formatters:**
+In addition to Tabulator's built-in formatters, these custom formatters are available:
+- `scientific`: Exponential notation (e.g., "1.23e-05") - use `formatterParams: {precision: 3}`
+- `signed`: Explicit +/- prefix (e.g., "+1.234") - use `formatterParams: {precision: 3, showPositive: true}`
+- `badge`: Colored pill/badge for categorical values - use `formatterParams: {colorMap: {"Up": "#FF0000"}, defaultColor: "#888"}`
+
+```python
+column_definitions=[
+    {'field': 'pvalue', 'title': 'P-value', 'formatter': 'scientific', 'formatterParams': {'precision': 2}},
+    {'field': 'log2fc', 'title': 'Log2 FC', 'formatter': 'signed', 'formatterParams': {'precision': 3}},
+    {'field': 'regulation', 'title': 'Status', 'formatter': 'badge',
+     'formatterParams': {'colorMap': {'Up': '#d62728', 'Down': '#1f77b4', 'NS': '#888888'}}},
+]
+```
+
 ### LinePlot
 
 Stick-style line plot using Plotly.js for mass spectra visualization.
@@ -192,6 +208,80 @@ Heatmap(
 - `min_points`: Target size for downsampling (default: 20000)
 - `x_bins`, `y_bins`: Grid resolution for spatial binning
 - `colorscale`: Plotly colorscale name (default: 'Portland')
+- `log_scale`: Use log10 color mapping (default: True). Set to False for linear.
+- `intensity_label`: Custom colorbar label (default: 'Intensity')
+
+**Linear scale example:**
+```python
+Heatmap(
+    cache_id="psm_scores",
+    data_path="psm_data.parquet",
+    x_column='rt',
+    y_column='mz',
+    intensity_column='score',
+    log_scale=False,              # Linear color mapping
+    intensity_label='Score',      # Custom colorbar label
+    colorscale='Blues',
+)
+```
+
+**Categorical mode:**
+Use `category_column` for discrete coloring by category instead of continuous intensity colorscale:
+
+```python
+Heatmap(
+    cache_id="samples_heatmap",
+    data_path="samples.parquet",
+    x_column='retention_time',
+    y_column='mass',
+    intensity_column='intensity',
+    category_column='sample_group',  # Color by category instead of intensity
+    category_colors={                 # Optional custom colors
+        'Control': '#1f77b4',
+        'Treatment_A': '#ff7f0e',
+        'Treatment_B': '#2ca02c',
+    },
+)
+```
+
+### VolcanoPlot
+
+Interactive volcano plot for differential expression analysis with significance thresholds.
+
+```python
+from openms_insight import VolcanoPlot
+
+VolcanoPlot(
+    cache_id="de_volcano",
+    data_path="differential_expression.parquet",
+    log2fc_column='log2FC',
+    pvalue_column='pvalue',
+    label_column='protein_name',       # Optional: labels for significant points
+    filters={'comparison': 'comparison_id'},
+    interactivity={'protein': 'protein_id'},
+    title="Differential Expression",
+    x_label="Log2 Fold Change",
+    y_label="-log10(p-value)",
+    up_color='#d62728',               # Color for up-regulated
+    down_color='#1f77b4',             # Color for down-regulated
+    ns_color='#888888',               # Color for not significant
+)(
+    state_manager=state_manager,
+    fc_threshold=1.0,                  # Fold change threshold (render-time)
+    p_threshold=0.05,                  # P-value threshold (render-time)
+    max_labels=20,                     # Max labels to show
+)
+```
+
+**Key parameters:**
+- `log2fc_column`: Column with log2 fold change values
+- `pvalue_column`: Column with p-values (automatically converted to -log10)
+- `label_column`: Optional column for point labels
+- `up_color`, `down_color`, `ns_color`: Colors for significance categories
+- `fc_threshold`, `p_threshold`: Significance thresholds (passed at render time, not cached)
+- `max_labels`: Maximum number of labels to display on significant points
+
+**Render-time thresholds:** The `fc_threshold` and `p_threshold` are passed via `__call__()`, not `__init__()`. This allows instant threshold adjustment without cache invalidation.
 
 ### SequenceView
 
@@ -255,6 +345,7 @@ All components accept these common arguments:
 | `interactivity` | `Dict[str, str]` | `None` | Map identifier -> column for click actions |
 | `cache_path` | `str` | `"."` | Base directory for cache storage |
 | `regenerate_cache` | `bool` | `False` | Force cache regeneration |
+| `height` | `int` | `400` | Component height in pixels (render-time parameter) |
 
 ## Memory-Efficient Preprocessing
 
@@ -338,6 +429,14 @@ npm run dev
 SVC_DEV_MODE=true SVC_DEV_URL=http://localhost:5173 streamlit run app.py
 ```
 
+### Debug Mode
+
+Enable hash tracking logs to debug data synchronization issues:
+
+```bash
+SVC_DEBUG_HASH=true streamlit run app.py
+```
+
 ### Running Tests
 
 ```bash

{openms_insight-0.1.4 → openms_insight-0.1.6}/openms_insight/__init__.py

@@ -9,13 +9,14 @@ from .components.heatmap import Heatmap
 from .components.lineplot import LinePlot
 from .components.sequenceview import SequenceView, SequenceViewResult
 from .components.table import Table
+from .components.volcanoplot import VolcanoPlot
 from .core.base import BaseComponent
 from .core.cache import CacheMissError
 from .core.registry import get_component_class, register_component
 from .core.state import StateManager
 from .rendering.bridge import clear_component_annotations, get_component_annotations
 
-__version__ = "0.1.0"
+__version__ = "0.1.6"
 
 __all__ = [
     # Core
@@ -28,6 +29,7 @@ __all__ = [
     "Table",
     "LinePlot",
     "Heatmap",
+    "VolcanoPlot",
     "SequenceView",
     "SequenceViewResult",
     # Utilities

{openms_insight-0.1.4 → openms_insight-0.1.6}/openms_insight/components/__init__.py

@@ -3,9 +3,11 @@
 from .heatmap import Heatmap
 from .lineplot import LinePlot
 from .table import Table
+from .volcanoplot import VolcanoPlot
 
 __all__ = [
     "Table",
     "LinePlot",
     "Heatmap",
+    "VolcanoPlot",
 ]

{openms_insight-0.1.4 → openms_insight-0.1.6}/openms_insight/components/heatmap.py

@@ -86,9 +86,14 @@ class Heatmap(BaseComponent):
         x_label: Optional[str] = None,
         y_label: Optional[str] = None,
         colorscale: str = "Portland",
+        reversescale: bool = False,
         use_simple_downsample: bool = False,
         use_streaming: bool = True,
         categorical_filters: Optional[List[str]] = None,
+        category_column: Optional[str] = None,
+        category_colors: Optional[Dict[str, str]] = None,
+        log_scale: bool = True,
+        intensity_label: Optional[str] = None,
         **kwargs,
     ):
         """
@@ -133,6 +138,18 @@ class Heatmap(BaseComponent):
                 are sent to the client regardless of filter selection. Should be
                 used for filters with a small number of unique values (<20).
                 Example: ['im_dimension'] for ion mobility filtering.
+            category_column: Optional column name for categorical coloring.
+                When provided, points are colored by discrete category values
+                instead of the continuous intensity colorscale. Useful for
+                condition-based heatmaps (e.g., coloring by sample group).
+            category_colors: Optional mapping of category values to colors.
+                Keys should match values in category_column.
+                Values should be CSS color strings (e.g., '#FF0000', 'red').
+                If not provided, default Plotly colors will be used.
+            log_scale: If True (default), apply log10 transformation to intensity
+                values for color mapping. Set to False for linear color mapping.
+            intensity_label: Custom label for the colorbar. Default is "Intensity".
+                Useful when displaying non-intensity values like scores or counts.
             **kwargs: Additional configuration options
         """
         self._x_column = x_column
@@ -147,7 +164,12 @@ class Heatmap(BaseComponent):
         self._x_label = x_label or x_column
         self._y_label = y_label or y_column
         self._colorscale = colorscale
+        self._reversescale = reversescale
         self._use_simple_downsample = use_simple_downsample
+        self._category_column = category_column
+        self._category_colors = category_colors or {}
+        self._log_scale = log_scale
+        self._intensity_label = intensity_label
         self._use_streaming = use_streaming
         self._categorical_filters = categorical_filters or []
 
@@ -176,6 +198,8 @@ class Heatmap(BaseComponent):
             use_simple_downsample=use_simple_downsample,
             use_streaming=use_streaming,
             categorical_filters=categorical_filters,
+            category_column=category_column,
+            category_colors=category_colors,
             **kwargs,
         )
 
@@ -202,6 +226,10 @@ class Heatmap(BaseComponent):
             "x_label": self._x_label,
             "y_label": self._y_label,
             "colorscale": self._colorscale,
+            "category_column": self._category_column,
+            "log_scale": self._log_scale,
+            "intensity_label": self._intensity_label,
+            # Note: category_colors is render-time styling, doesn't affect cache
         }
 
     def _restore_cache_config(self, config: Dict[str, Any]) -> None:
@@ -223,6 +251,10 @@ class Heatmap(BaseComponent):
         self._x_label = config.get("x_label", self._x_column)
         self._y_label = config.get("y_label", self._y_column)
         self._colorscale = config.get("colorscale", "Portland")
+        self._category_column = config.get("category_column")
+        self._log_scale = config.get("log_scale", True)
+        self._intensity_label = config.get("intensity_label")
+        # category_colors is not stored in cache (render-time styling)
 
     def get_state_dependencies(self) -> list:
         """
@@ -457,9 +489,7 @@ class Heatmap(BaseComponent):
                 filtered_total = filtered_data.select(pl.len()).collect().item()
 
                 # Compute level sizes for this filtered subset (2× for cache buffer)
-                level_sizes = compute_compression_levels(
-                    cache_target, filtered_total
-                )
+                level_sizes = compute_compression_levels(cache_target, filtered_total)
 
                 print(
                     f"[HEATMAP]   Value {filter_value}: {filtered_total:,} pts → levels {level_sizes}",
@@ -937,12 +967,15 @@ class Heatmap(BaseComponent):
 
         zoom = state.get(self._zoom_identifier)
 
-        # Build columns to select
+        # Build columns to select (filter out None values)
         columns_to_select = [
-            self._x_column,
-            self._y_column,
-            self._intensity_column,
+            col
+            for col in [self._x_column, self._y_column, self._intensity_column]
+            if col is not None
         ]
+        # Include category column if specified
+        if self._category_column and self._category_column not in columns_to_select:
+            columns_to_select.append(self._category_column)
         # Include columns needed for interactivity
         if self._interactivity:
             for col in self._interactivity.values():
@@ -995,17 +1028,25 @@ class Heatmap(BaseComponent):
                     columns=columns_to_select,
                     filter_defaults=self._filter_defaults,
                 )
-                # Sort by intensity ascending so high-intensity points are drawn on top
-                df_pandas = df_pandas.sort_values(self._intensity_column).reset_index(
-                    drop=True
-                )
+                # Sort by intensity ascending so high-intensity points are drawn on top (scattergl)
+                if (
+                    self._intensity_column
+                    and self._intensity_column in df_pandas.columns
+                ):
+                    df_pandas = df_pandas.sort_values(
+                        self._intensity_column, ascending=True
+                    ).reset_index(drop=True)
             else:
                 # No filters to apply - levels already filtered by categorical filter
                 schema_names = data.collect_schema().names()
                 available_cols = [c for c in columns_to_select if c in schema_names]
                 df_polars = data.select(available_cols).collect()
-                # Sort by intensity ascending so high-intensity points are drawn on top
-                df_polars = df_polars.sort(self._intensity_column)
+                # Sort by intensity ascending so high-intensity points are drawn on top (scattergl)
+                if (
+                    self._intensity_column
+                    and self._intensity_column in df_polars.columns
+                ):
+                    df_polars = df_polars.sort(self._intensity_column)
                 data_hash = compute_dataframe_hash(df_polars)
                 df_pandas = df_polars.to_pandas()
         else:
@@ -1017,8 +1058,9 @@ class Heatmap(BaseComponent):
             # Select only needed columns
             available_cols = [c for c in columns_to_select if c in df_polars.columns]
             df_polars = df_polars.select(available_cols)
-            # Sort by intensity ascending so high-intensity points are drawn on top
-            df_polars = df_polars.sort(self._intensity_column)
+            # Sort by intensity ascending so high-intensity points are drawn on top (scattergl)
+            if self._intensity_column and self._intensity_column in df_polars.columns:
+                df_polars = df_polars.sort(self._intensity_column)
             print(
                 f"[HEATMAP] Selected {len(df_polars)} pts for zoom, levels={level_sizes}",
                 file=sys.stderr,
@@ -1046,6 +1088,7 @@ class Heatmap(BaseComponent):
             "xLabel": self._x_label,
             "yLabel": self._y_label,
             "colorscale": self._colorscale,
+            "reversescale": self._reversescale,
             "zoomIdentifier": self._zoom_identifier,
             "interactivity": self._interactivity,
         }
@@ -1053,6 +1096,17 @@ class Heatmap(BaseComponent):
         if self._title:
             args["title"] = self._title
 
+        # Add category column configuration for categorical coloring mode
+        if self._category_column:
+            args["categoryColumn"] = self._category_column
+            if self._category_colors:
+                args["categoryColors"] = self._category_colors
+
+        # Add log scale and intensity label configuration
+        args["logScale"] = self._log_scale
+        if self._intensity_label:
+            args["intensityLabel"] = self._intensity_label
+
         # Add any extra config options
         args.update(self._config)