openms-insight 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

openms_insight/preprocessing/__init__.py

@@ -10,6 +10,10 @@ from .filtering import (
     filter_by_index,
     filter_by_selection,
 )
+from .scatter import (
+    build_scatter_columns,
+    prepare_scatter_data,
+)
 
 __all__ = [
     "filter_by_selection",
@@ -18,4 +22,6 @@ __all__ = [
     "compute_compression_levels",
     "downsample_2d",
     "downsample_2d_simple",
+    "build_scatter_columns",
+    "prepare_scatter_data",
 ]

openms_insight/preprocessing/compression.py

@@ -6,7 +6,8 @@ data, enabling efficient visualization of datasets with millions of points.
 Supports both streaming (lazy) and eager downsampling approaches.
 """
 
-from typing import List, Optional, Union
+import math
+from typing import List, Optional, Tuple, Union
 
 import numpy as np
 import polars as pl
@@ -19,6 +20,59 @@ except ImportError:
     HAS_SCIPY = False
 
 
+def compute_optimal_bins(
+    target_points: int,
+    x_range: Tuple[float, float],
+    y_range: Tuple[float, float],
+) -> Tuple[int, int]:
+    """
+    Compute optimal x_bins, y_bins for even spatial distribution.
+
+    The bin grid matches the data's aspect ratio so bins are approximately
+    square in data space. Total bins ≈ target_points for 1 point per bin.
+
+    Solves the system:
+        x_bins × y_bins = target_points
+        x_bins / y_bins = aspect_ratio
+
+    Solution:
+        y_bins = sqrt(target_points / aspect_ratio)
+        x_bins = sqrt(target_points × aspect_ratio)
+
+    Args:
+        target_points: Target number of bins (and thus max points with 1 per bin)
+        x_range: (x_min, x_max) data range
+        y_range: (y_min, y_max) data range
+
+    Returns:
+        (x_bins, y_bins) tuple
+
+    Examples:
+        >>> compute_optimal_bins(10000, (0, 1000), (0, 100))  # 10:1 aspect
+        (316, 31)
+        >>> compute_optimal_bins(10000, (0, 100), (0, 100))   # 1:1 aspect
+        (100, 100)
+    """
+    x_span = x_range[1] - x_range[0]
+    y_span = y_range[1] - y_range[0]
+
+    # Handle edge cases
+    if y_span < 1e-10:
+        y_span = x_span if x_span > 1e-10 else 1.0
+    if x_span < 1e-10:
+        x_span = y_span
+
+    aspect_ratio = x_span / y_span
+
+    # Clamp to reasonable bounds (avoid extreme rectangles)
+    aspect_ratio = max(0.05, min(20.0, aspect_ratio))
+
+    y_bins = max(1, int(math.sqrt(target_points / aspect_ratio)))
+    x_bins = max(1, int(math.sqrt(target_points * aspect_ratio)))
+
+    return x_bins, y_bins
+
+
 def compute_compression_levels(min_size: int, total: int) -> List[int]:
     """
     Compute logarithmically-spaced compression level target sizes.

openms_insight/preprocessing/scatter.py

@@ -0,0 +1,136 @@
+"""Shared utilities for scatter-based components (Heatmap, VolcanoPlot)."""
+
+from typing import Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+import polars as pl
+
+from .filtering import compute_dataframe_hash, filter_and_collect_cached
+
+
+def build_scatter_columns(
+    x_column: str,
+    y_column: str,
+    value_column: str,
+    interactivity: Optional[Dict[str, str]] = None,
+    filters: Optional[Dict[str, str]] = None,
+    extra_columns: Optional[List[str]] = None,
+) -> List[str]:
+    """
+    Build list of columns needed for scatter-based component.
+
+    Includes x, y, value columns plus any columns needed for
+    interactivity and filtering.
+
+    Args:
+        x_column: Name of x-axis column
+        y_column: Name of y-axis column
+        value_column: Name of value column (intensity, -log10(pvalue), etc.)
+        interactivity: Mapping of identifier names to column names for clicks
+        filters: Mapping of identifier names to column names for filtering
+        extra_columns: Additional columns to include (e.g., label_column)
+
+    Returns:
+        List of unique column names to select
+    """
+    columns = [x_column, y_column, value_column]
+
+    # Include columns needed for interactivity
+    if interactivity:
+        for col in interactivity.values():
+            if col not in columns:
+                columns.append(col)
+
+    # Include filter columns
+    if filters:
+        for col in filters.values():
+            if col not in columns:
+                columns.append(col)
+
+    # Include extra columns (e.g., label column for VolcanoPlot)
+    if extra_columns:
+        for col in extra_columns:
+            if col and col not in columns:
+                columns.append(col)
+
+    return columns
+
+
+def prepare_scatter_data(
+    data: pl.LazyFrame,
+    x_column: str,
+    y_column: str,
+    value_column: str,
+    filters: Optional[Dict[str, str]],
+    state: Dict[str, Any],
+    filter_defaults: Optional[Dict[str, Any]] = None,
+    interactivity: Optional[Dict[str, str]] = None,
+    extra_columns: Optional[List[str]] = None,
+    sort_by_value: bool = True,
+    sort_ascending: bool = True,
+) -> Tuple[pd.DataFrame, str]:
+    """
+    Prepare scatter data for Vue component.
+
+    Common data preparation for scatter-based components (Heatmap, VolcanoPlot).
+    Applies filters, selects columns, optionally sorts, and returns pandas
+    DataFrame with hash for change detection.
+
+    Args:
+        data: LazyFrame with scatter data
+        x_column: Name of x-axis column
+        y_column: Name of y-axis column
+        value_column: Name of value column (intensity, -log10(pvalue), etc.)
+        filters: Mapping of identifier names to column names for filtering
+        state: Current selection state from StateManager
+        filter_defaults: Optional default values for filters when state is None
+        interactivity: Mapping of identifier names to column names for clicks
+        extra_columns: Additional columns to include (e.g., label_column)
+        sort_by_value: If True, sort by value_column (default: True)
+        sort_ascending: Sort order - True for ascending (default: True)
+            Ascending puts high values on top in scatter plots.
+
+    Returns:
+        Tuple of (pandas DataFrame, hash string for change detection)
+    """
+    # Build columns to select
+    columns = build_scatter_columns(
+        x_column=x_column,
+        y_column=y_column,
+        value_column=value_column,
+        interactivity=interactivity,
+        filters=filters,
+        extra_columns=extra_columns,
+    )
+
+    # Apply filters if any
+    if filters:
+        df_pandas, data_hash = filter_and_collect_cached(
+            data,
+            filters,
+            state,
+            columns=columns,
+            filter_defaults=filter_defaults,
+        )
+
+        # Sort by value column so high-value points are drawn on top
+        if sort_by_value and len(df_pandas) > 0 and value_column in df_pandas.columns:
+            df_pandas = df_pandas.sort_values(
+                value_column, ascending=sort_ascending
+            ).reset_index(drop=True)
+
+        return df_pandas, data_hash
+    else:
+        # No filters - just select columns and collect
+        schema_names = data.collect_schema().names()
+        available_cols = [c for c in columns if c in schema_names]
+        df_polars = data.select(available_cols).collect()
+
+        # Sort by value column
+        if sort_by_value and len(df_polars) > 0 and value_column in df_polars.columns:
+            df_polars = df_polars.sort(value_column, descending=not sort_ascending)
+
+        data_hash = compute_dataframe_hash(df_polars)
+        df_pandas = df_polars.to_pandas()
+
+        return df_pandas, data_hash

openms_insight/rendering/bridge.py

@@ -2,6 +2,7 @@
 
 import hashlib
 import json
+import logging
 import os
 from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
 
@@ -9,6 +10,10 @@ import pandas as pd
 import polars as pl
 import streamlit as st
 
+# Configure debug logging for hash tracking
+_DEBUG_HASH_TRACKING = os.environ.get("SVC_DEBUG_HASH", "").lower() == "true"
+_logger = logging.getLogger(__name__)
+
 
 def _make_hashable(value: Any) -> Any:
     """
@@ -316,8 +321,10 @@ def render_component(
 
     # Generate unique key if not provided (needed for cache)
     # Use cache_id instead of id(component) since components are recreated each rerun
+    # Use JSON serialization for deterministic key generation (hash() can vary)
     if key is None:
-        key = f"svc_{component._cache_id}_{hash(str(component._interactivity))}"
+        interactivity_str = json.dumps(component._interactivity or {}, sort_keys=True)
+        key = f"svc_{component._cache_id}_{hashlib.md5(interactivity_str.encode()).hexdigest()[:8]}"
 
     # Check if component has required filters without values
     # Don't send potentially huge unfiltered datasets - wait for filter selection
@@ -389,6 +396,16 @@ def render_component(
     # so normal comparison works for all components including those with dynamic annotations
     data_changed = (vue_echoed_hash is None) or (vue_echoed_hash != data_hash)
 
+    # Debug logging for hash tracking issues
+    if _DEBUG_HASH_TRACKING:
+        _logger.warning(
+            f"[HashTrack] {component._cache_id}: "
+            f"data_changed={data_changed}, "
+            f"vue_echoed={vue_echoed_hash[:8] if vue_echoed_hash else 'None'}, "
+            f"data_hash={data_hash[:8] if data_hash else 'None'}, "
+            f"key={hash_tracking_key[:50]}..."
+        )
+
     # Only include full data if hash changed
     if data_changed:
         # Convert any non-pandas data to pandas for Arrow serialization
@@ -448,10 +465,12 @@ def render_component(
     # Update state from Vue response
     if result is not None:
         # Store Vue's echoed hash for next render comparison
-        # ALWAYS update from Vue's echo - if Vue lost its data (page navigation),
-        # it echoes None, and we need to know that to resend data next time
+        # Only store non-None hashes - Vue echoes None during initialization
+        # before receiving data, which would corrupt our tracking. Preserving
+        # the previous valid hash prevents unnecessary data resends.
         vue_hash = result.get("_vueDataHash")
-        st.session_state[_VUE_ECHOED_HASH_KEY][hash_tracking_key] = vue_hash
+        if vue_hash is not None:
+            st.session_state[_VUE_ECHOED_HASH_KEY][hash_tracking_key] = vue_hash
 
         # Capture annotations from Vue (e.g., from SequenceView)
         # Use hash-based change detection for robustness

{openms_insight-0.1.3.dist-info → openms_insight-0.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openms-insight
-Version: 0.1.3
+Version: 0.1.5
 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.3.dist-info → openms_insight-0.1.5.dist-info}/RECORD

@@ -1,28 +1,30 @@
-openms_insight/__init__.py,sha256=Iv9w0J_7J3pMsyvM4xaYDMWt6IvrtAt6WqOmJ-_tUxk,1044
-openms_insight/components/__init__.py,sha256=T9mUxfgFUiHILmXh1VjcGVlnRvuxRMqi_GJJYOmJKwY,177
-openms_insight/components/heatmap.py,sha256=hCvmtGsFYiZCoIrk4L9KsD7FC6j1GBljwZgKxjNkLPo,38143
+openms_insight/__init__.py,sha256=gOX7oIlGQ7TJmd5BfyL5SCQhV6IaPPsOGXOaWOCnCN8,1111
+openms_insight/components/__init__.py,sha256=Lcg-D0FILta-YVgMJBlWMKLKC5G5kXOqdy9hBOENABw,233
+openms_insight/components/heatmap.py,sha256=psrdW4gNzZR1jAIox9YS9EHaZaTRrDHFR0t2_0APU9Y,47214
 openms_insight/components/lineplot.py,sha256=I-JPvDzCr3Nu8Boc1V4D8QQ1bHgTqvM6CbeoIe7zJ-s,30896
 openms_insight/components/sequenceview.py,sha256=0pDOE0xeoc1-85QZNGdNwwoBwXi-5MFfeb9pCcOi6rc,30274
 openms_insight/components/table.py,sha256=wmq1rjGVe4Ef0SAf5p85pfVCeyLlVevZnxBc9EIg2uk,16458
+openms_insight/components/volcanoplot.py,sha256=F-cmYxJMKXVK-aYJpifp8be7nB8hkQd2kLi9DrBElD8,15155
 openms_insight/core/__init__.py,sha256=EPjKX_FFQRgO8mWHs59I-o0BiuzEMzEU1Pfu9YOfLC4,338
-openms_insight/core/base.py,sha256=t8G_hertREPf1qSqoDU6PGDKFV_mnvOyLUNtaNbnQvQ,18745
+openms_insight/core/base.py,sha256=6hxmII90LlbwTy06BJvUdJjXpd8Oqjqdt452AJixJSs,19742
 openms_insight/core/cache.py,sha256=3fnPDWjuWUnxazK2XflcUIeRZZPQ3N45kAKYu-xGBKw,1197
 openms_insight/core/registry.py,sha256=Hak80Jqhx0qa4gbd1YolNZnM6xBrS8I4U_X7zC0bQ8Y,2108
 openms_insight/core/state.py,sha256=_vNYxYHYFgIigbkqYwkIO6cBGFJyF2VN9dr7CBEAQbY,6873
 openms_insight/core/subprocess_preprocess.py,sha256=m9FbAAFy9Do1Exlh-m4Wo-LDwv6yHlEI4klz5OVwemc,3133
-openms_insight/preprocessing/__init__.py,sha256=hXKTI9zHtMtHojqXq_0V62xfNokozpnpRAwEnxs81fM,461
-openms_insight/preprocessing/compression.py,sha256=phe0D568lpNiwkPGI7AXWg9i3iX3xgEyi7JIqydCtxk,10664
+openms_insight/preprocessing/__init__.py,sha256=xoGdhNVrX8Ty3ywmyaCcWAO3a6QlKceO1xxsy1C8ZTI,596
+openms_insight/preprocessing/compression.py,sha256=T4YbX9PUlfTfPit_kpuLZn8hYpqLYu3xtTme_CG2ymc,12241
 openms_insight/preprocessing/filtering.py,sha256=fkmaIXfR5hfjyWfaMYqaeybMHaZjvUZYaKCqvxPOWMQ,14152
+openms_insight/preprocessing/scatter.py,sha256=2ifCNTUKHEW9UVpv4z9c5GaLnz5zw9o1119IenzAe9s,4703
 openms_insight/rendering/__init__.py,sha256=ApHvKeh87yY4GTIEai-tCeIXpNbwOXWlmcmIwMMRZYc,198
-openms_insight/rendering/bridge.py,sha256=i8cZq_ra13XpuV1KT0qC6Jf4VCAe4BGrLE-ybrFHwZE,19408
+openms_insight/rendering/bridge.py,sha256=Y5ckR0Gb7s88bJJpVnM_fEZzN2MppN_PfDnsceAr3Mc,20276
 openms_insight/js-component/dist/index.html,sha256=LSJ3B_YmGUrCCdZ1UaZO2p6Wqsih6nTH62Z_0uZxpD8,430
-openms_insight/js-component/dist/assets/index.css,sha256=PBjVykbu3UhFmwMAFJEcMjQYPEU0IpGuaQWwt0c9r7E,884228
-openms_insight/js-component/dist/assets/index.js,sha256=AMODoRTGWDTNhCjNUMgTrvicm7ctOdrkohM8NIC9xtM,6063763
+openms_insight/js-component/dist/assets/index.css,sha256=wFvo7FbG132LL7uw0slXfrL_oSQ8u2RKL1DW9hD9-kk,884264
+openms_insight/js-component/dist/assets/index.js,sha256=EGp5VXlZWHp0jIsOg5jJeYaCz_eDN2R0KDT_btyc6ww,6074760
 openms_insight/js-component/dist/assets/materialdesignicons-webfont.eot,sha256=CxgxBNL8XyYZbnc8d72vLgVQn9QlnS0V7O3Kebh-hPk,1307880
 openms_insight/js-component/dist/assets/materialdesignicons-webfont.ttf,sha256=YeirpaTpgf4iz3yOi82-oAR251xiw38Bv37jM2HWhCg,1307660
 openms_insight/js-component/dist/assets/materialdesignicons-webfont.woff,sha256=pZKKDVwvYk5G-Y2bFcL2AEU3f3xZTdeKF1kTLqO0Y-s,587984
 openms_insight/js-component/dist/assets/materialdesignicons-webfont.woff2,sha256=Zi_vqPL4qVwYWI0hd0eJwQfGTnccvmWmmvRikcQxGvw,403216
-openms_insight-0.1.3.dist-info/METADATA,sha256=k_FqXgopIKrICwhW5qcs1xXsYvfav1JOhTD6kQ410wA,12807
-openms_insight-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-openms_insight-0.1.3.dist-info/licenses/LICENSE,sha256=INFF4rOMmpah7Oi14hLqu7NTOsx56KRRNChAAUcfh2E,1823
-openms_insight-0.1.3.dist-info/RECORD,,
+openms_insight-0.1.5.dist-info/METADATA,sha256=ccUljk6Ixse_tMFpebzWg0Vj_qo4ZGa328flIrBzMKc,16670
+openms_insight-0.1.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openms_insight-0.1.5.dist-info/licenses/LICENSE,sha256=INFF4rOMmpah7Oi14hLqu7NTOsx56KRRNChAAUcfh2E,1823
+openms_insight-0.1.5.dist-info/RECORD,,