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

openms_insight/components/table.py

@@ -6,7 +6,7 @@ import polars as pl
 
 from ..core.base import BaseComponent
 from ..core.registry import register_component
-from ..preprocessing.filtering import compute_dataframe_hash, filter_and_collect_cached
+from ..preprocessing.filtering import filter_and_collect_cached
 
 
 @register_component("table")
@@ -57,14 +57,14 @@ class Table(BaseComponent):
         regenerate_cache: bool = False,
         column_definitions: Optional[List[Dict[str, Any]]] = None,
         title: Optional[str] = None,
-        index_field: str = 'id',
+        index_field: str = "id",
         go_to_fields: Optional[List[str]] = None,
-        layout: str = 'fitDataFill',
+        layout: str = "fitDataFill",
         default_row: int = 0,
         initial_sort: Optional[List[Dict[str, Any]]] = None,
         pagination: bool = True,
         page_size: int = 100,
-        **kwargs
+        **kwargs,
     ):
         """
         Initialize the Table component.
@@ -138,7 +138,7 @@ class Table(BaseComponent):
             initial_sort=initial_sort,
             pagination=pagination,
             page_size=page_size,
-            **kwargs
+            **kwargs,
         )
 
     def _get_cache_config(self) -> Dict[str, Any]:
@@ -149,10 +149,29 @@ class Table(BaseComponent):
             Dict of config values that affect preprocessing
         """
         return {
-            'column_definitions': self._column_definitions,
-            'index_field': self._index_field,
+            "column_definitions": self._column_definitions,
+            "index_field": self._index_field,
+            "title": self._title,
+            "go_to_fields": self._go_to_fields,
+            "layout": self._layout,
+            "default_row": self._default_row,
+            "initial_sort": self._initial_sort,
+            "pagination": self._pagination,
+            "page_size": self._page_size,
         }
 
+    def _restore_cache_config(self, config: Dict[str, Any]) -> None:
+        """Restore component-specific configuration from cached config."""
+        self._column_definitions = config.get("column_definitions")
+        self._index_field = config.get("index_field", "id")
+        self._title = config.get("title")
+        self._go_to_fields = config.get("go_to_fields")
+        self._layout = config.get("layout", "fitDataFill")
+        self._default_row = config.get("default_row", 0)
+        self._initial_sort = config.get("initial_sort")
+        self._pagination = config.get("pagination", True)
+        self._page_size = config.get("page_size", 100)
+
     def _get_row_group_size(self) -> int:
         """
         Get optimal row group size for parquet writing.
@@ -195,31 +214,40 @@ class Table(BaseComponent):
             self._column_definitions = []
             for name, dtype in zip(schema.names(), schema.dtypes()):
                 col_def: Dict[str, Any] = {
-                    'field': name,
-                    'title': name.replace('_', ' ').title(),
-                    'headerTooltip': True,
+                    "field": name,
+                    "title": name.replace("_", " ").title(),
+                    "headerTooltip": True,
                 }
                 # Set sorter based on data type
-                if dtype in (pl.Int8, pl.Int16, pl.Int32, pl.Int64,
-                             pl.UInt8, pl.UInt16, pl.UInt32, pl.UInt64,
-                             pl.Float32, pl.Float64):
-                    col_def['sorter'] = 'number'
-                    col_def['hozAlign'] = 'right'
+                if dtype in (
+                    pl.Int8,
+                    pl.Int16,
+                    pl.Int32,
+                    pl.Int64,
+                    pl.UInt8,
+                    pl.UInt16,
+                    pl.UInt32,
+                    pl.UInt64,
+                    pl.Float32,
+                    pl.Float64,
+                ):
+                    col_def["sorter"] = "number"
+                    col_def["hozAlign"] = "right"
                 elif dtype == pl.Boolean:
-                    col_def['sorter'] = 'boolean'
+                    col_def["sorter"] = "boolean"
                 elif dtype in (pl.Date, pl.Datetime, pl.Time):
-                    col_def['sorter'] = 'date'
+                    col_def["sorter"] = "date"
                 else:
-                    col_def['sorter'] = 'string'
+                    col_def["sorter"] = "string"
 
                 self._column_definitions.append(col_def)
 
         # Store column definitions in preprocessed data for serialization
-        self._preprocessed_data['column_definitions'] = self._column_definitions
+        self._preprocessed_data["column_definitions"] = self._column_definitions
 
         # Store LazyFrame for streaming to disk (filter happens at render time)
         # Base class will use sink_parquet() to stream without full materialization
-        self._preprocessed_data['data'] = data  # Keep lazy
+        self._preprocessed_data["data"] = data  # Keep lazy
 
     def _get_columns_to_select(self) -> Optional[List[str]]:
         """Get list of columns needed for this table."""
@@ -227,9 +255,9 @@ class Table(BaseComponent):
             return None
 
         columns_to_select = [
-            col_def['field']
+            col_def["field"]
             for col_def in self._column_definitions
-            if 'field' in col_def
+            if "field" in col_def
         ]
         # Always include index field for row identification
         if self._index_field and self._index_field not in columns_to_select:
@@ -249,11 +277,11 @@ class Table(BaseComponent):
 
     def _get_vue_component_name(self) -> str:
         """Return the Vue component name."""
-        return 'TabulatorTable'
+        return "TabulatorTable"
 
     def _get_data_key(self) -> str:
         """Return the key used to send primary data to Vue."""
-        return 'tableData'
+        return "tableData"
 
     def _prepare_vue_data(self, state: Dict[str, Any]) -> Dict[str, Any]:
         """
@@ -272,7 +300,7 @@ class Table(BaseComponent):
         columns = self._get_columns_to_select()
 
         # Get cached data (DataFrame or LazyFrame)
-        data = self._preprocessed_data.get('data')
+        data = self._preprocessed_data.get("data")
         if data is None:
             # Fallback to raw data if available
             data = self._raw_data
@@ -290,7 +318,7 @@ class Table(BaseComponent):
             filter_defaults=self._filter_defaults,
         )
 
-        return {'tableData': df_pandas, '_hash': data_hash}
+        return {"tableData": df_pandas, "_hash": data_hash}
 
     def _get_component_args(self) -> Dict[str, Any]:
         """
@@ -302,29 +330,29 @@ class Table(BaseComponent):
         # Get column definitions (may have been loaded from cache)
         column_defs = self._column_definitions
         if column_defs is None:
-            column_defs = self._preprocessed_data.get('column_definitions', [])
+            column_defs = self._preprocessed_data.get("column_definitions", [])
 
         args: Dict[str, Any] = {
-            'componentType': self._get_vue_component_name(),
-            'columnDefinitions': column_defs,
-            'tableIndexField': self._index_field,
-            'tableLayoutParam': self._layout,
-            'defaultRow': self._default_row,
+            "componentType": self._get_vue_component_name(),
+            "columnDefinitions": column_defs,
+            "tableIndexField": self._index_field,
+            "tableLayoutParam": self._layout,
+            "defaultRow": self._default_row,
             # Pass interactivity so Vue knows which identifier to update on row click
-            'interactivity': self._interactivity,
+            "interactivity": self._interactivity,
             # Pagination settings
-            'pagination': self._pagination,
-            'pageSize': self._page_size,
+            "pagination": self._pagination,
+            "pageSize": self._page_size,
         }
 
         if self._title:
-            args['title'] = self._title
+            args["title"] = self._title
 
         if self._go_to_fields:
-            args['goToFields'] = self._go_to_fields
+            args["goToFields"] = self._go_to_fields
 
         if self._initial_sort:
-            args['initialSort'] = self._initial_sort
+            args["initialSort"] = self._initial_sort
 
         # Add any extra config options
         args.update(self._config)
@@ -335,8 +363,8 @@ class Table(BaseComponent):
         self,
         field: str,
         formatter: str,
-        formatter_params: Optional[Dict[str, Any]] = None
-    ) -> 'Table':
+        formatter_params: Optional[Dict[str, Any]] = None,
+    ) -> "Table":
         """
         Add or update a column formatter.
 
@@ -349,10 +377,10 @@ class Table(BaseComponent):
             Self for method chaining
         """
         for col_def in self._column_definitions or []:
-            if col_def.get('field') == field:
-                col_def['formatter'] = formatter
+            if col_def.get("field") == field:
+                col_def["formatter"] = formatter
                 if formatter_params:
-                    col_def['formatterParams'] = formatter_params
+                    col_def["formatterParams"] = formatter_params
                 break
         return self
 
@@ -360,10 +388,10 @@ class Table(BaseComponent):
         self,
         field: str,
         precision: int = 2,
-        symbol: str = '',
-        thousand: str = ',',
-        decimal: str = '.'
-    ) -> 'Table':
+        symbol: str = "",
+        thousand: str = ",",
+        decimal: str = ".",
+    ) -> "Table":
         """
         Format a column as currency/money.
 
@@ -379,13 +407,13 @@ class Table(BaseComponent):
         """
         return self.with_column_formatter(
             field,
-            'money',
+            "money",
             {
-                'precision': precision,
-                'symbol': symbol,
-                'thousand': thousand,
-                'decimal': decimal,
-            }
+                "precision": precision,
+                "symbol": symbol,
+                "thousand": thousand,
+                "decimal": decimal,
+            },
         )
 
     def with_progress_bar(
@@ -393,8 +421,8 @@ class Table(BaseComponent):
         field: str,
         min_val: float = 0,
         max_val: float = 100,
-        color: Optional[str] = None
-    ) -> 'Table':
+        color: Optional[str] = None,
+    ) -> "Table":
         """
         Format a column as a progress bar.
 
@@ -407,7 +435,7 @@ class Table(BaseComponent):
         Returns:
             Self for method chaining
         """
-        params: Dict[str, Any] = {'min': min_val, 'max': max_val}
+        params: Dict[str, Any] = {"min": min_val, "max": max_val}
         if color:
-            params['color'] = color
-        return self.with_column_formatter(field, 'progress', params)
+            params["color"] = color
+        return self.with_column_formatter(field, "progress", params)

openms_insight/core/__init__.py

@@ -1,9 +1,9 @@
 """Core infrastructure for openms_insight."""
 
 from .base import BaseComponent
-from .state import StateManager
-from .registry import register_component, get_component_class
 from .cache import CacheMissError
+from .registry import get_component_class, register_component
+from .state import StateManager
 
 __all__ = [
     "BaseComponent",

openms_insight/core/base.py

@@ -1,11 +1,12 @@
 """Base component class for all visualization components."""
 
-from abc import ABC, abstractmethod
-from datetime import datetime
 import hashlib
 import json
+from abc import ABC, abstractmethod
+from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, List, Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
 import polars as pl
 
 from .cache import CacheMissError, get_cache_dir
@@ -15,7 +16,8 @@ if TYPE_CHECKING:
 
 # Cache format version - increment when cache structure changes
 # Version 2: Added sorting by filter columns + smaller row groups for predicate pushdown
-CACHE_VERSION = 2
+# Version 3: Downcast numeric types (Int64→Int32, Float64→Float32) for efficient transfer
+CACHE_VERSION = 3
 
 
 class BaseComponent(ABC):
@@ -49,15 +51,24 @@ class BaseComponent(ABC):
         interactivity: Optional[Dict[str, str]] = None,
         cache_path: str = ".",
         regenerate_cache: bool = False,
-        **kwargs
+        **kwargs,
     ):
         """
         Initialize the component.
 
+        Components can be created in two modes:
+
+        1. **Creation mode** (data provided): Creates cache with specified config.
+           All configuration (filters, interactivity, component-specific) is stored.
+
+        2. **Reconstruction mode** (no data): Loads everything from cache.
+           Only cache_id and cache_path are needed. All configuration is restored
+           from the cached manifest. Any other parameters passed are ignored.
+
         Args:
             cache_id: Unique identifier for this component's cache (MANDATORY).
                 Creates a folder {cache_path}/{cache_id}/ for cached data.
-            data: Polars LazyFrame with source data. Optional if cache exists.
+            data: Polars LazyFrame with source data. Required for creation mode.
             data_path: Path to parquet file with source data. Preferred over
                 data= for large datasets as preprocessing runs in a subprocess
                 to ensure memory is released after cache creation.
@@ -83,23 +94,51 @@ class BaseComponent(ABC):
 
         self._cache_id = cache_id
         self._cache_dir = get_cache_dir(cache_path, cache_id)
-        self._filters = filters or {}
-        self._filter_defaults = filter_defaults or {}
-        self._interactivity = interactivity or {}
         self._preprocessed_data: Dict[str, Any] = {}
-        self._config = kwargs
 
-        # Check if we should load from cache or preprocess
-        if regenerate_cache or not self._is_cache_valid():
-            if data is None and data_path is None:
+        # Determine mode: reconstruction (no data) or creation (data provided)
+        has_data = data is not None or data_path is not None
+
+        # Check if any configuration arguments were explicitly provided
+        # Note: We only check filters/interactivity/filter_defaults because component-
+        # specific kwargs always have default values passed by subclasses
+        has_config = (
+            filters is not None
+            or filter_defaults is not None
+            or interactivity is not None
+        )
+
+        if not has_data and not regenerate_cache:
+            # Reconstruction mode - only cache_id and cache_path allowed
+            if has_config:
                 raise CacheMissError(
-                    f"Cache not found at '{self._cache_dir}' and no data provided. "
-                    f"Either provide data=, data_path=, or ensure cache exists."
+                    "Configuration arguments (filters, interactivity, filter_defaults) "
+                    "require data= or data_path= to be provided. "
+                    "For reconstruction from cache, use only cache_id and cache_path."
                 )
+            if not self._cache_exists():
+                raise CacheMissError(
+                    f"Cache not found at '{self._cache_dir}'. "
+                    f"Provide data= or data_path= to create the cache."
+                )
+            self._raw_data = None
+            self._load_from_cache()
+        else:
+            # Creation mode - use provided config
+            if not has_data:
+                raise CacheMissError(
+                    "regenerate_cache=True requires data= or data_path= to be provided."
+                )
+
+            self._filters = filters or {}
+            self._filter_defaults = filter_defaults or {}
+            self._interactivity = interactivity or {}
+            self._config = kwargs
 
             if data_path is not None:
                 # Subprocess preprocessing - memory released after cache creation
                 from .subprocess_preprocess import preprocess_component
+
                 preprocess_component(
                     type(self),
                     data_path=data_path,
@@ -108,20 +147,16 @@ class BaseComponent(ABC):
                     filters=filters,
                     filter_defaults=filter_defaults,
                     interactivity=interactivity,
-                    **kwargs
+                    **kwargs,
                 )
                 self._raw_data = None
                 self._load_from_cache()
             else:
-                # In-process preprocessing (backward compatible)
+                # In-process preprocessing
                 self._raw_data = data
                 self._validate_mappings()
                 self._preprocess()
                 self._save_to_cache()
-        else:
-            # Load from valid cache
-            self._raw_data = None
-            self._load_from_cache()
 
     def _validate_mappings(self) -> None:
         """Validate that filter and interactivity columns exist in the data schema."""
@@ -162,7 +197,7 @@ class BaseComponent(ABC):
         config_dict = {
             "filters": self._filters,
             "interactivity": self._interactivity,
-            **self._get_cache_config()
+            **self._get_cache_config(),
         }
         config_str = json.dumps(config_dict, sort_keys=True, default=str)
         return hashlib.sha256(config_str.encode()).hexdigest()
@@ -175,15 +210,17 @@ class BaseComponent(ABC):
         """Get path to preprocessed data directory."""
         return self._cache_dir / "preprocessed"
 
-    def _is_cache_valid(self) -> bool:
+    def _cache_exists(self) -> bool:
         """
-        Check if cache is valid and can be loaded.
+        Check if a valid cache exists that can be loaded.
 
-        Cache is valid when:
-        1. manifest.json exists
+        Cache exists when:
+        1. manifest.json exists and is readable
         2. version matches current CACHE_VERSION
         3. component_type matches
-        4. config_hash matches current config
+
+        Note: This does NOT check config hash. In reconstruction mode,
+        all configuration is restored from the cache manifest.
         """
         manifest_path = self._get_manifest_path()
         if not manifest_path.exists():
@@ -203,24 +240,32 @@ class BaseComponent(ABC):
         if manifest.get("component_type") != self._component_type:
             return False
 
-        # Check config hash
-        current_hash = self._compute_config_hash()
-        if manifest.get("config_hash") != current_hash:
-            return False
-
         return True
 
     def _load_from_cache(self) -> None:
-        """Load preprocessed data from cache."""
+        """Load all configuration and preprocessed data from cache.
+
+        Restores:
+        - filters mapping
+        - filter_defaults mapping
+        - interactivity mapping
+        - Component-specific configuration via _restore_cache_config()
+        - All preprocessed data files
+        """
         manifest_path = self._get_manifest_path()
         preprocessed_dir = self._get_preprocessed_dir()
 
         with open(manifest_path) as f:
             manifest = json.load(f)
 
-        # Load filters and interactivity from manifest
+        # Restore filters, filter_defaults, and interactivity from manifest
         self._filters = manifest.get("filters", {})
+        self._filter_defaults = manifest.get("filter_defaults", {})
         self._interactivity = manifest.get("interactivity", {})
+        self._config = manifest.get("config", {})
+
+        # Restore component-specific configuration
+        self._restore_cache_config(manifest.get("config", {}))
 
         # Load preprocessed data files
         data_files = manifest.get("data_files", {})
@@ -234,8 +279,26 @@ class BaseComponent(ABC):
         for key, value in data_values.items():
             self._preprocessed_data[key] = value
 
+    @abstractmethod
+    def _restore_cache_config(self, config: Dict[str, Any]) -> None:
+        """
+        Restore component-specific configuration from cached config dict.
+
+        Called during reconstruction mode to restore all component attributes
+        that were stored in the manifest's config section.
+
+        Args:
+            config: The config dict from manifest (result of _get_cache_config())
+        """
+        pass
+
     def _save_to_cache(self) -> None:
         """Save preprocessed data to cache."""
+        from ..preprocessing.filtering import (
+            optimize_for_transfer,
+            optimize_for_transfer_lazy,
+        )
+
         # Create directories
         self._cache_dir.mkdir(parents=True, exist_ok=True)
         preprocessed_dir = self._get_preprocessed_dir()
@@ -249,23 +312,30 @@ class BaseComponent(ABC):
             "config_hash": self._compute_config_hash(),
             "config": self._get_cache_config(),
             "filters": self._filters,
+            "filter_defaults": self._filter_defaults,
             "interactivity": self._interactivity,
             "data_files": {},
             "data_values": {},
         }
 
-        # Save preprocessed data - stream LazyFrames directly to disk
+        # Save preprocessed data with type optimization for efficient transfer
+        # Float64→Float32 reduces Arrow payload size
+        # Int64→Int32 (when safe) avoids BigInt overhead in JavaScript
         for key, value in self._preprocessed_data.items():
             if isinstance(value, pl.LazyFrame):
                 filename = f"{key}.parquet"
                 filepath = preprocessed_dir / filename
-                # Stream directly to disk without full materialization
-                value.sink_parquet(filepath, compression='zstd')
+                # Apply streaming-safe optimization (Float64→Float32 only)
+                # Int64 bounds checking would require collect(), breaking streaming
+                value = optimize_for_transfer_lazy(value)
+                value.sink_parquet(filepath, compression="zstd")
                 manifest["data_files"][key] = filename
             elif isinstance(value, pl.DataFrame):
                 filename = f"{key}.parquet"
                 filepath = preprocessed_dir / filename
-                value.write_parquet(filepath, compression='zstd')
+                # Full optimization including Int64→Int32 with bounds checking
+                value = optimize_for_transfer(value)
+                value.write_parquet(filepath, compression="zstd")
                 manifest["data_files"][key] = filename
             elif self._is_json_serializable(value):
                 manifest["data_values"][key] = value
@@ -323,10 +393,7 @@ class BaseComponent(ABC):
         pass
 
     @abstractmethod
-    def _prepare_vue_data(
-        self,
-        state: Dict[str, Any]
-    ) -> Dict[str, Any]:
+    def _prepare_vue_data(self, state: Dict[str, Any]) -> Dict[str, Any]:
         """
         Prepare data payload for Vue component.
 
@@ -395,8 +462,8 @@ class BaseComponent(ABC):
     def __call__(
         self,
         key: Optional[str] = None,
-        state_manager: Optional['StateManager'] = None,
-        height: Optional[int] = None
+        state_manager: Optional["StateManager"] = None,
+        height: Optional[int] = None,
     ) -> Any:
         """
         Render the component in Streamlit.
@@ -410,17 +477,14 @@ class BaseComponent(ABC):
         Returns:
             The value returned by the Vue component (usually selection state)
         """
-        from .state import get_default_state_manager
         from ..rendering.bridge import render_component
+        from .state import get_default_state_manager
 
         if state_manager is None:
             state_manager = get_default_state_manager()
 
         return render_component(
-            component=self,
-            state_manager=state_manager,
-            key=key,
-            height=height
+            component=self, state_manager=state_manager, key=key, height=height
         )
 
     def __repr__(self) -> str:

openms_insight/core/registry.py

@@ -1,12 +1,12 @@
 """Component type registry for serialization and deserialization."""
 
-from typing import Dict, Type, TYPE_CHECKING
+from typing import TYPE_CHECKING, Dict, Type
 
 if TYPE_CHECKING:
     from .base import BaseComponent
 
 # Global registry mapping component type names to their classes
-_COMPONENT_REGISTRY: Dict[str, Type['BaseComponent']] = {}
+_COMPONENT_REGISTRY: Dict[str, Type["BaseComponent"]] = {}
 
 
 def register_component(name: str):
@@ -24,7 +24,8 @@ def register_component(name: str):
         class Table(BaseComponent):
             ...
     """
-    def decorator(cls: Type['BaseComponent']) -> Type['BaseComponent']:
+
+    def decorator(cls: Type["BaseComponent"]) -> Type["BaseComponent"]:
         if name in _COMPONENT_REGISTRY:
             raise ValueError(
                 f"Component type '{name}' is already registered to "
@@ -37,7 +38,7 @@ def register_component(name: str):
     return decorator
 
 
-def get_component_class(name: str) -> Type['BaseComponent']:
+def get_component_class(name: str) -> Type["BaseComponent"]:
     """
     Get a component class by its registered name.
 
@@ -59,7 +60,7 @@ def get_component_class(name: str) -> Type['BaseComponent']:
     return _COMPONENT_REGISTRY[name]
 
 
-def list_registered_components() -> Dict[str, Type['BaseComponent']]:
+def list_registered_components() -> Dict[str, Type["BaseComponent"]]:
     """
     Get all registered component types.