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

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.5"
 
 __all__ = [
     # Core
@@ -28,6 +29,7 @@ __all__ = [
     "Table",
     "LinePlot",
     "Heatmap",
+    "VolcanoPlot",
     "SequenceView",
     "SequenceViewResult",
     # Utilities

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/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)
 

openms_insight/components/volcanoplot.py

@@ -0,0 +1,374 @@
+"""VolcanoPlot component for differential expression visualization."""
+
+from typing import Any, Dict, Optional
+
+import polars as pl
+
+from ..core.base import BaseComponent
+from ..core.registry import register_component
+from ..preprocessing.scatter import build_scatter_columns
+
+
+@register_component("volcanoplot")
+class VolcanoPlot(BaseComponent):
+    """
+    Interactive volcano plot for differential expression analysis.
+
+    Displays log2 fold change (x-axis) vs -log10(p-value) (y-axis) with
+    three-category coloring based on significance thresholds. Thresholds
+    are passed at render time to avoid cache invalidation when adjusting
+    sliders.
+
+    Features:
+    - Client-side significance computation (instant threshold updates)
+    - Three-category coloring (up-regulated, down-regulated, not significant)
+    - Threshold lines at ±fc_threshold and -log10(p_threshold)
+    - Optional labels on significant points
+    - Click-to-select with cross-component linking
+    - SVG export
+
+    Example:
+        volcano = VolcanoPlot(
+            cache_id="protein_volcano",
+            data_path="proteins.parquet",
+            log2fc_column="log2FC",
+            pvalue_column="pvalue",
+            label_column="protein_name",
+            interactivity={'protein': 'protein_id'},
+            filters={'comparison': 'comparison_id'},
+        )
+
+        # Thresholds passed at render time - no cache impact
+        volcano(
+            state_manager=state,
+            fc_threshold=1.0,
+            p_threshold=0.05,
+            height=500,
+        )
+    """
+
+    _component_type: str = "volcanoplot"
+
+    def __init__(
+        self,
+        cache_id: str,
+        log2fc_column: str = "log2FC",
+        pvalue_column: str = "pvalue",
+        data: Optional[pl.LazyFrame] = None,
+        data_path: Optional[str] = None,
+        label_column: Optional[str] = None,
+        filters: Optional[Dict[str, str]] = None,
+        filter_defaults: Optional[Dict[str, Any]] = None,
+        interactivity: Optional[Dict[str, str]] = None,
+        cache_path: str = ".",
+        regenerate_cache: bool = False,
+        title: Optional[str] = None,
+        x_label: Optional[str] = None,
+        y_label: Optional[str] = None,
+        up_color: str = "#E74C3C",
+        down_color: str = "#3498DB",
+        ns_color: str = "#95A5A6",
+        show_threshold_lines: bool = True,
+        threshold_line_style: str = "dash",
+        **kwargs,
+    ):
+        """
+        Initialize the VolcanoPlot component.
+
+        Args:
+            cache_id: Unique identifier for this component's cache (MANDATORY).
+                Creates a folder {cache_path}/{cache_id}/ for cached data.
+            log2fc_column: Name of column for log2 fold change (x-axis).
+            pvalue_column: Name of column for p-value. Will be transformed
+                to -log10(pvalue) for display on y-axis.
+            data: Polars LazyFrame with volcano data. Optional if cache exists.
+            data_path: Path to parquet file (preferred for large datasets).
+            label_column: Name of column for point labels (shown on hover and
+                optionally as annotations on significant points).
+            filters: Mapping of identifier names to column names for filtering.
+                Example: {'comparison': 'comparison_id'} filters by comparison.
+            filter_defaults: Default values for filter identifiers when no
+                selection is present in state.
+            interactivity: Mapping of identifier names to column names for clicks.
+                When a point is clicked, sets each identifier to the clicked
+                point's value in the corresponding column.
+            cache_path: Base path for cache storage. Default "." (current dir).
+            regenerate_cache: If True, regenerate cache even if valid cache exists.
+            title: Plot title displayed above the volcano plot.
+            x_label: X-axis label (default: "log2 Fold Change").
+            y_label: Y-axis label (default: "-log10(p-value)").
+            up_color: Color for up-regulated points (default: red #E74C3C).
+            down_color: Color for down-regulated points (default: blue #3498DB).
+            ns_color: Color for not significant points (default: gray #95A5A6).
+            show_threshold_lines: Show threshold lines on plot (default: True).
+            threshold_line_style: Line style for thresholds (default: "dash").
+            **kwargs: Additional configuration options.
+        """
+        self._log2fc_column = log2fc_column
+        self._pvalue_column = pvalue_column
+        self._label_column = label_column
+        self._title = title
+        self._x_label = x_label or "log2 Fold Change"
+        self._y_label = y_label or "-log10(p-value)"
+        self._up_color = up_color
+        self._down_color = down_color
+        self._ns_color = ns_color
+        self._show_threshold_lines = show_threshold_lines
+        self._threshold_line_style = threshold_line_style
+
+        # Render-time threshold values (set in __call__)
+        self._current_fc_threshold: float = 1.0
+        self._current_p_threshold: float = 0.05
+        self._current_max_labels: int = 10
+
+        # Computed -log10(pvalue) column name
+        self._neglog10p_column = "_neglog10_pvalue"
+
+        super().__init__(
+            cache_id=cache_id,
+            data=data,
+            data_path=data_path,
+            filters=filters,
+            filter_defaults=filter_defaults,
+            interactivity=interactivity,
+            cache_path=cache_path,
+            regenerate_cache=regenerate_cache,
+            **kwargs,
+        )
+
+    def _validate_columns(self, schema: pl.Schema) -> None:
+        """Validate that required columns exist in the data schema."""
+        available = set(schema.names())
+
+        required = [self._log2fc_column, self._pvalue_column]
+        missing = [col for col in required if col not in available]
+        if missing:
+            raise ValueError(
+                f"Missing required columns: {missing}. "
+                f"Available columns: {sorted(available)}"
+            )
+
+        if self._label_column and self._label_column not in available:
+            raise ValueError(
+                f"Label column '{self._label_column}' not found. "
+                f"Available columns: {sorted(available)}"
+            )
+
+    def _get_component_config_hash_inputs(self) -> Dict[str, Any]:
+        """Get inputs for component config hash (cache invalidation)."""
+        return {
+            "log2fc_column": self._log2fc_column,
+            "pvalue_column": self._pvalue_column,
+            "label_column": self._label_column,
+            # Note: thresholds are NOT included - they're render-time params
+        }
+
+    def _get_cache_config(self) -> Dict[str, Any]:
+        """Get configuration that affects cache validity."""
+        return {
+            "log2fc_column": self._log2fc_column,
+            "pvalue_column": self._pvalue_column,
+            "label_column": self._label_column,
+            "title": self._title,
+            "x_label": self._x_label,
+            "y_label": self._y_label,
+            "up_color": self._up_color,
+            "down_color": self._down_color,
+            "ns_color": self._ns_color,
+            "show_threshold_lines": self._show_threshold_lines,
+            "threshold_line_style": self._threshold_line_style,
+        }
+
+    def _restore_cache_config(self, config: Dict[str, Any]) -> None:
+        """Restore component-specific configuration from cached config."""
+        self._log2fc_column = config.get("log2fc_column", "log2FC")
+        self._pvalue_column = config.get("pvalue_column", "pvalue")
+        self._label_column = config.get("label_column")
+        self._title = config.get("title")
+        self._x_label = config.get("x_label", "log2 Fold Change")
+        self._y_label = config.get("y_label", "-log10(p-value)")
+        self._up_color = config.get("up_color", "#E74C3C")
+        self._down_color = config.get("down_color", "#3498DB")
+        self._ns_color = config.get("ns_color", "#95A5A6")
+        self._show_threshold_lines = config.get("show_threshold_lines", True)
+        self._threshold_line_style = config.get("threshold_line_style", "dash")
+
+    def _preprocess(self) -> None:
+        """Preprocess data for volcano plot.
+
+        Computes -log10(pvalue) and caches the result. No downsampling is
+        typically needed for volcano plots (<10K proteins), but we handle
+        it if datasets get large.
+        """
+        if self._raw_data is None:
+            raise ValueError("No data provided and no cache exists")
+
+        # Build list of columns to select
+        # Note: pvalue is passed as y_column only (no duplicate value_column)
+        extra_cols = [self._label_column] if self._label_column else []
+        columns = build_scatter_columns(
+            x_column=self._log2fc_column,
+            y_column=self._pvalue_column,
+            value_column=self._pvalue_column,
+            interactivity=self._interactivity,
+            filters=self._filters,
+            extra_columns=extra_cols if extra_cols else None,
+        )
+        # Remove duplicates while preserving order
+        columns = list(dict.fromkeys(columns))
+
+        # Select columns and compute -log10(pvalue)
+        schema_names = self._raw_data.collect_schema().names()
+        available_cols = [c for c in columns if c in schema_names]
+
+        df = (
+            self._raw_data.select(available_cols)
+            .with_columns(
+                pl.when(pl.col(self._pvalue_column) > 0)
+                .then(-pl.col(self._pvalue_column).log(10))
+                .otherwise(0.0)
+                .alias(self._neglog10p_column)
+            )
+            .collect()
+        )
+
+        self._preprocessed_data = {"volcanoData": df}
+
+    def _get_vue_component_name(self) -> str:
+        """Return the Vue component name."""
+        return "PlotlyVolcano"
+
+    def _get_data_key(self) -> str:
+        """Return the key for the primary data in Vue payload."""
+        return "volcanoData"
+
+    def _prepare_vue_data(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """Prepare filtered data for Vue component.
+
+        Uses shared prepare_scatter_data for filtering and conversion.
+        """
+        if self._preprocessed_data is None or not self._preprocessed_data:
+            self._load_preprocessed_data()
+
+        data = self._preprocessed_data["volcanoData"]
+        # Handle both LazyFrame (from cache) and DataFrame
+        if isinstance(data, pl.LazyFrame):
+            df_polars = data.collect()
+        else:
+            df_polars = data
+
+        # Build columns to select (remove duplicates)
+        extra_cols = (
+            [self._label_column, self._pvalue_column]
+            if self._label_column
+            else [self._pvalue_column]
+        )
+        columns = build_scatter_columns(
+            x_column=self._log2fc_column,
+            y_column=self._neglog10p_column,
+            value_column=self._neglog10p_column,
+            interactivity=self._interactivity,
+            filters=self._filters,
+            extra_columns=extra_cols,
+        )
+        # Remove duplicates while preserving order
+        columns = list(dict.fromkeys(columns))
+
+        # Apply filters if any
+        if self._filters:
+            from ..preprocessing.filtering import (
+                compute_dataframe_hash,
+                filter_and_collect_cached,
+            )
+
+            df_pandas, data_hash = filter_and_collect_cached(
+                df_polars.lazy(),
+                self._filters,
+                state,
+                columns=columns,
+                filter_defaults=self._filter_defaults,
+            )
+
+            # Sort by significance (most significant on top for rendering)
+            if len(df_pandas) > 0 and self._neglog10p_column in df_pandas.columns:
+                df_pandas = df_pandas.sort_values(
+                    self._neglog10p_column, ascending=True
+                ).reset_index(drop=True)
+
+            return {"volcanoData": df_pandas, "_hash": data_hash}
+        else:
+            # No filters - select columns and convert to pandas
+            available_cols = [c for c in columns if c in df_polars.columns]
+            df_filtered = df_polars.select(available_cols)
+
+            # Sort by significance
+            if self._neglog10p_column in df_filtered.columns:
+                df_filtered = df_filtered.sort(self._neglog10p_column, descending=False)
+
+            from ..preprocessing.filtering import compute_dataframe_hash
+
+            data_hash = compute_dataframe_hash(df_filtered)
+            df_pandas = df_filtered.to_pandas()
+
+            return {"volcanoData": df_pandas, "_hash": data_hash}
+
+    def _get_component_args(self) -> Dict[str, Any]:
+        """Return configuration for Vue component."""
+        return {
+            "componentType": self._get_vue_component_name(),
+            "log2fcColumn": self._log2fc_column,
+            "neglog10pColumn": self._neglog10p_column,
+            "pvalueColumn": self._pvalue_column,
+            "labelColumn": self._label_column,
+            "title": self._title,
+            "xLabel": self._x_label,
+            "yLabel": self._y_label,
+            "upColor": self._up_color,
+            "downColor": self._down_color,
+            "nsColor": self._ns_color,
+            "showThresholdLines": self._show_threshold_lines,
+            "thresholdLineStyle": self._threshold_line_style,
+            # Render-time threshold values
+            "fcThreshold": self._current_fc_threshold,
+            "pThreshold": self._current_p_threshold,
+            "maxLabels": self._current_max_labels,
+            "interactivity": self._interactivity or {},
+        }
+
+    def __call__(
+        self,
+        key: Optional[str] = None,
+        state_manager: Optional[Any] = None,
+        height: Optional[int] = None,
+        fc_threshold: float = 1.0,
+        p_threshold: float = 0.05,
+        max_labels: int = 10,
+    ) -> Any:
+        """
+        Render the volcano plot component.
+
+        Args:
+            key: Optional unique key for this component instance.
+            state_manager: StateManager for cross-component linking.
+            height: Optional height override in pixels.
+            fc_threshold: Fold change threshold for significance
+                (default: 1.0, meaning |log2FC| >= 1).
+            p_threshold: P-value threshold for significance
+                (default: 0.05). Points with p < threshold are significant.
+            max_labels: Maximum number of labels to show on significant
+                points (default: 10). Labels are shown for top N by
+                significance.
+
+        Returns:
+            Component result for Streamlit rendering.
+        """
+        # Store render-time threshold values
+        self._current_fc_threshold = fc_threshold
+        self._current_p_threshold = p_threshold
+        self._current_max_labels = max_labels
+
+        # Update height if provided
+        if height is not None:
+            self._height = height
+
+        return super().__call__(key=key, state_manager=state_manager, height=height)

openms_insight/core/base.py

@@ -19,6 +19,10 @@ if TYPE_CHECKING:
 # Version 3: Downcast numeric types (Int64→Int32, Float64→Float32) for efficient transfer
 CACHE_VERSION = 3
 
+# Default height for components when not specified
+# This is the single source of truth for component height
+DEFAULT_COMPONENT_HEIGHT = 400
+
 
 class BaseComponent(ABC):
     """
@@ -485,7 +489,8 @@ class BaseComponent(ABC):
             key: Optional unique key for the Streamlit component
             state_manager: Optional StateManager for cross-component state.
                 If not provided, uses a default shared StateManager.
-            height: Optional height in pixels for the component
+            height: Optional height in pixels for the component.
+                If not provided, uses DEFAULT_COMPONENT_HEIGHT (400px).
 
         Returns:
             The value returned by the Vue component (usually selection state)
@@ -496,6 +501,10 @@ class BaseComponent(ABC):
         if state_manager is None:
             state_manager = get_default_state_manager()
 
+        # Use default height if not specified
+        if height is None:
+            height = DEFAULT_COMPONENT_HEIGHT
+
         return render_component(
             component=self, state_manager=state_manager, key=key, height=height
         )