PyPI - openms-insight - Versions diffs - 0.1.0__py3-none-any.whl - Mend

openms-insight 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

openms_insight/__init__.py +32 -0
openms_insight/components/__init__.py +11 -0
openms_insight/components/heatmap.py +823 -0
openms_insight/components/lineplot.py +492 -0
openms_insight/components/sequenceview.py +384 -0
openms_insight/components/table.py +400 -0
openms_insight/core/__init__.py +14 -0
openms_insight/core/base.py +413 -0
openms_insight/core/cache.py +39 -0
openms_insight/core/registry.py +82 -0
openms_insight/core/state.py +215 -0
openms_insight/js-component/dist/assets/index.css +5 -0
openms_insight/js-component/dist/assets/index.js +4220 -0
openms_insight/js-component/dist/assets/materialdesignicons-webfont.eot +0 -0
openms_insight/js-component/dist/assets/materialdesignicons-webfont.ttf +0 -0
openms_insight/js-component/dist/assets/materialdesignicons-webfont.woff +0 -0
openms_insight/js-component/dist/assets/materialdesignicons-webfont.woff2 +0 -0
openms_insight/js-component/dist/index.html +14 -0
openms_insight/preprocessing/__init__.py +22 -0
openms_insight/preprocessing/compression.py +338 -0
openms_insight/preprocessing/filtering.py +316 -0
openms_insight/rendering/__init__.py +8 -0
openms_insight/rendering/bridge.py +312 -0
openms_insight-0.1.0.dist-info/METADATA +256 -0
openms_insight-0.1.0.dist-info/RECORD +27 -0
openms_insight-0.1.0.dist-info/WHEEL +4 -0
openms_insight-0.1.0.dist-info/licenses/LICENSE +29 -0

openms_insight/js-component/dist/assets/materialdesignicons-webfont.eot ADDED Viewed

Binary file

openms_insight/js-component/dist/assets/materialdesignicons-webfont.ttf ADDED Viewed

Binary file

openms_insight/js-component/dist/assets/materialdesignicons-webfont.woff ADDED Viewed

Binary file

openms_insight/js-component/dist/assets/materialdesignicons-webfont.woff2 ADDED Viewed

Binary file

openms_insight/js-component/dist/index.html ADDED Viewed

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <link rel="icon" href="/favicon.ico">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Streamlit Vue Components</title>
+    <script type="module" crossorigin src="./assets/index.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index.css">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

openms_insight/preprocessing/__init__.py ADDED Viewed

@@ -0,0 +1,22 @@
+"""Preprocessing utilities for data transformation and filtering."""
+from .filtering import (
+    filter_by_selection,
+    filter_by_index,
+    filter_and_collect_cached,
+)
+from .compression import (
+    compute_compression_levels,
+    downsample_2d,
+    downsample_2d_simple,
+)
+__all__ = [
+    "filter_by_selection",
+    "filter_by_index",
+    "filter_and_collect_cached",
+    "compute_compression_levels",
+    "downsample_2d",
+    "downsample_2d_simple",
+]

openms_insight/preprocessing/compression.py ADDED Viewed

@@ -0,0 +1,338 @@
+"""Compression utilities for large 2D datasets (heatmaps).
+This module provides functions for multi-resolution downsampling of 2D scatter
+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 numpy as np
+import polars as pl
+try:
+    from scipy.stats import binned_statistic_2d
+    HAS_SCIPY = True
+except ImportError:
+    HAS_SCIPY = False
+def compute_compression_levels(min_size: int, total: int) -> List[int]:
+    """
+    Compute logarithmically-spaced compression level target sizes.
+    Given a minimum target size and total data size, computes intermediate
+    compression levels at powers of 10.
+    Args:
+        min_size: Minimum/smallest compression level size (e.g., 20000)
+        total: Total number of data points
+    Returns:
+        List of target sizes, smallest first. Always returns at least one level.
+        For small datasets (total <= min_size), returns [total] to preserve all data.
+    Examples:
+        >>> compute_compression_levels(20000, 1_000_000)
+        [20000, 200000]
+        >>> compute_compression_levels(20000, 50_000)
+        [20000]
+        >>> compute_compression_levels(20000, 15_000)
+        [15000]
+    """
+    if total <= min_size:
+        # Still return at least one level with all data
+        return [total]
+    # Compute powers of 10 between min and total
+    min_power = int(np.log10(min_size))
+    max_power = int(np.log10(total))
+    if min_power >= max_power:
+        # Data is between min_size and 10x min_size - one downsampled level
+        return [min_size]
+    # Generate levels at each power of 10, scaled by the fractional part
+    scale_factor = int(10 ** (np.log10(min_size) % 1))
+    levels = np.logspace(
+        min_power,
+        max_power,
+        max_power - min_power + 1,
+        dtype='int'
+    ) * scale_factor
+    # Filter out levels >= total (don't include full resolution for large datasets)
+    levels = levels[levels < total].tolist()
+    # Ensure at least one level exists
+    if not levels:
+        levels = [min_size]
+    return levels
+def downsample_2d(
+    data: Union[pl.LazyFrame, pl.DataFrame],
+    max_points: int = 20000,
+    x_column: str = 'x',
+    y_column: str = 'y',
+    intensity_column: str = 'intensity',
+    x_bins: int = 400,
+    y_bins: int = 50,
+) -> pl.LazyFrame:
+    """
+    Downsample 2D scatter data while preserving high-intensity points.
+    Uses 2D binning to spatially partition data, then keeps the top N
+    highest-intensity points per bin. This preserves visually important
+    features (peaks) while reducing total point count.
+    Args:
+        data: Input data as Polars LazyFrame or DataFrame
+        max_points: Maximum number of points to keep
+        x_column: Name of x-axis column
+        y_column: Name of y-axis column
+        intensity_column: Name of intensity/value column for ranking
+        x_bins: Number of bins along x-axis
+        y_bins: Number of bins along y-axis
+    Returns:
+        Downsampled data as Polars LazyFrame
+    Raises:
+        ImportError: If scipy is not installed
+        ValueError: If x_bins * y_bins > max_points
+    """
+    if not HAS_SCIPY:
+        raise ImportError(
+            "scipy is required for downsample_2d. "
+            "Install with: pip install scipy"
+        )
+    if (x_bins * y_bins) > max_points:
+        raise ValueError(
+            f"Number of bins ({x_bins * y_bins}) exceeds max_points ({max_points}). "
+            "Reduce x_bins or y_bins."
+        )
+    # Ensure we're working with a LazyFrame
+    if isinstance(data, pl.DataFrame):
+        data = data.lazy()
+    # Sort by intensity (descending) to prioritize high-intensity points
+    sorted_data = (
+        data
+        .sort([x_column, intensity_column], descending=[False, True])
+        .with_columns([
+            pl.int_range(pl.len()).over(x_column).alias('_rank')
+        ])
+        .sort(['_rank', intensity_column], descending=[False, True])
+    )
+    # Collect for scipy binning (requires numpy arrays)
+    collected = sorted_data.collect()
+    total_count = len(collected)
+    if total_count <= max_points:
+        # No downsampling needed
+        return collected.drop('_rank').lazy()
+    # Extract arrays for scipy
+    x_array = collected[x_column].to_numpy()
+    y_array = collected[y_column].to_numpy()
+    intensity_array = collected[intensity_column].to_numpy()
+    # Compute 2D bins
+    count, _, _, mapping = binned_statistic_2d(
+        x_array, y_array, intensity_array, 'count',
+        bins=[x_bins, y_bins],
+        expand_binnumbers=True
+    )
+    # Add bin indices to dataframe
+    binned_data = (
+        collected.lazy()
+        .with_columns([
+            pl.Series('_x_bin', mapping[0] - 1),  # scipy uses 1-based indexing
+            pl.Series('_y_bin', mapping[1] - 1)
+        ])
+    )
+    # Compute max peaks per bin to stay under limit
+    counted_peaks = 0
+    max_peaks_per_bin = -1
+    new_count = 0
+    while (counted_peaks + new_count) < max_points:
+        max_peaks_per_bin += 1
+        counted_peaks += new_count
+        new_count = np.sum(count.flatten() >= (max_peaks_per_bin + 1))
+        if counted_peaks >= total_count:
+            break
+    # Keep top N peaks per bin
+    result = (
+        binned_data
+        .group_by(['_x_bin', '_y_bin'])
+        .head(max_peaks_per_bin)
+        .sort(intensity_column)
+        .drop(['_rank', '_x_bin', '_y_bin'])
+    )
+    return result
+def downsample_2d_simple(
+    data: Union[pl.LazyFrame, pl.DataFrame],
+    max_points: int = 20000,
+    intensity_column: str = 'intensity',
+) -> pl.LazyFrame:
+    """
+    Simple downsampling by keeping highest-intensity points.
+    A simpler alternative to downsample_2d that doesn't require scipy.
+    Less spatially aware but still preserves important peaks.
+    Args:
+        data: Input data as Polars LazyFrame or DataFrame
+        max_points: Maximum number of points to keep
+        intensity_column: Name of intensity column for ranking
+    Returns:
+        Downsampled data as Polars LazyFrame
+    """
+    if isinstance(data, pl.DataFrame):
+        data = data.lazy()
+    return (
+        data
+        .sort(intensity_column, descending=True)
+        .head(max_points)
+    )
+def downsample_2d_streaming(
+    data: Union[pl.LazyFrame, pl.DataFrame],
+    max_points: int = 20000,
+    x_column: str = 'x',
+    y_column: str = 'y',
+    intensity_column: str = 'intensity',
+    x_bins: int = 400,
+    y_bins: int = 50,
+    x_range: Optional[tuple] = None,
+    y_range: Optional[tuple] = None,
+) -> pl.LazyFrame:
+    """
+    Streaming 2D downsampling using pure Polars operations.
+    Uses Polars' lazy evaluation to downsample data without full materialization.
+    Creates spatial bins using integer division and keeps top-N highest-intensity
+    points per bin. Stays fully lazy - no .collect() is called.
+    Args:
+        data: Input data as Polars LazyFrame or DataFrame
+        max_points: Maximum number of points to keep
+        x_column: Name of x-axis column
+        y_column: Name of y-axis column
+        intensity_column: Name of intensity/value column for ranking
+        x_bins: Number of bins along x-axis
+        y_bins: Number of bins along y-axis
+        x_range: Optional (min, max) tuple for x-axis. If None, computed from data.
+        y_range: Optional (min, max) tuple for y-axis. If None, computed from data.
+    Returns:
+        Downsampled data as Polars LazyFrame (fully lazy, no collection)
+    """
+    if isinstance(data, pl.DataFrame):
+        data = data.lazy()
+    # Calculate points per bin
+    total_bins = x_bins * y_bins
+    points_per_bin = max(1, max_points // total_bins)
+    # Build binning expression using provided or computed ranges
+    if x_range is not None and y_range is not None:
+        x_min, x_max = x_range
+        y_min, y_max = y_range
+        # Use provided ranges for bin calculation
+        x_bin_expr = (
+            ((pl.col(x_column) - x_min) / (x_max - x_min + 1e-10) * x_bins)
+            .cast(pl.Int32)
+            .clip(0, x_bins - 1)
+            .alias('_x_bin')
+        )
+        y_bin_expr = (
+            ((pl.col(y_column) - y_min) / (y_max - y_min + 1e-10) * y_bins)
+            .cast(pl.Int32)
+            .clip(0, y_bins - 1)
+            .alias('_y_bin')
+        )
+        result = (
+            data
+            .with_columns([x_bin_expr, y_bin_expr])
+            .sort(intensity_column, descending=True)
+            .group_by(['_x_bin', '_y_bin'])
+            .head(points_per_bin)
+            .drop(['_x_bin', '_y_bin'])
+        )
+    else:
+        # Need to compute ranges - still lazy using over() window
+        # First pass: add normalized bin columns using min/max over entire frame
+        result = (
+            data
+            .with_columns([
+                # Compute bin indices using window functions for min/max
+                (
+                    (pl.col(x_column) - pl.col(x_column).min()) /
+                    (pl.col(x_column).max() - pl.col(x_column).min() + 1e-10) * x_bins
+                ).cast(pl.Int32).clip(0, x_bins - 1).alias('_x_bin'),
+                (
+                    (pl.col(y_column) - pl.col(y_column).min()) /
+                    (pl.col(y_column).max() - pl.col(y_column).min() + 1e-10) * y_bins
+                ).cast(pl.Int32).clip(0, y_bins - 1).alias('_y_bin'),
+            ])
+            .sort(intensity_column, descending=True)
+            .group_by(['_x_bin', '_y_bin'])
+            .head(points_per_bin)
+            .drop(['_x_bin', '_y_bin'])
+        )
+    return result
+def get_data_range(
+    data: Union[pl.LazyFrame, pl.DataFrame],
+    x_column: str,
+    y_column: str,
+) -> tuple:
+    """
+    Get the min/max ranges for x and y columns.
+    This requires a collect() operation but only fetches 4 scalar values.
+    Args:
+        data: Input data
+        x_column: X-axis column name
+        y_column: Y-axis column name
+    Returns:
+        Tuple of ((x_min, x_max), (y_min, y_max))
+    """
+    if isinstance(data, pl.DataFrame):
+        data = data.lazy()
+    stats = data.select([
+        pl.col(x_column).min().alias('x_min'),
+        pl.col(x_column).max().alias('x_max'),
+        pl.col(y_column).min().alias('y_min'),
+        pl.col(y_column).max().alias('y_max'),
+    ]).collect()
+    return (
+        (stats['x_min'][0], stats['x_max'][0]),
+        (stats['y_min'][0], stats['y_max'][0]),
+    )

openms_insight/preprocessing/filtering.py ADDED Viewed

@@ -0,0 +1,316 @@
+"""Data filtering utilities for selection-based filtering."""
+from typing import Any, Dict, List, Optional, Tuple, Union
+import hashlib
+import pandas as pd
+import polars as pl
+import streamlit as st
+def _make_cache_key(
+    filters: Dict[str, str],
+    state: Dict[str, Any],
+    filter_defaults: Optional[Dict[str, Any]] = None,
+) -> Tuple[Tuple[str, Any], ...]:
+    """
+    Create a hashable cache key from filters and state.
+    Only includes state values for identifiers that are in filters,
+    so cache is invalidated only when relevant selections change.
+    Args:
+        filters: Mapping of identifier names to column names
+        state: Current selection state
+        filter_defaults: Optional default values for filters when state is None
+    Returns:
+        Tuple of (identifier, value) pairs for use as cache key
+    """
+    relevant_state = []
+    for identifier in sorted(filters.keys()):
+        value = state.get(identifier)
+        # Apply default if value is None and default exists
+        if value is None and filter_defaults and identifier in filter_defaults:
+            value = filter_defaults[identifier]
+        relevant_state.append((identifier, value))
+    return tuple(relevant_state)
+def compute_dataframe_hash(df: pl.DataFrame) -> str:
+    """
+    Compute an efficient hash for a DataFrame without pickling.
+    Uses shape, column names, and sampled values to create a fast hash
+    that detects data changes without materializing extra copies.
+    Args:
+        df: Polars DataFrame to hash
+    Returns:
+        SHA256 hash string
+    """
+    # Build hash from metadata and sampled content
+    hash_parts = [
+        str(df.shape),  # (rows, cols)
+        str(df.columns),  # Column names
+    ]
+    # For small DataFrames, hash first/last values of each column
+    # For large DataFrames, this is still O(1) memory
+    if len(df) > 0:
+        # Sample first and last row for change detection
+        first_row = df.head(1).to_dicts()[0] if len(df) > 0 else {}
+        last_row = df.tail(1).to_dicts()[0] if len(df) > 0 else {}
+        hash_parts.append(str(first_row))
+        hash_parts.append(str(last_row))
+        # Add sum of numeric columns for content verification
+        for col in df.columns:
+            dtype = df[col].dtype
+            if dtype in (pl.Int8, pl.Int16, pl.Int32, pl.Int64,
+                         pl.UInt8, pl.UInt16, pl.UInt32, pl.UInt64,
+                         pl.Float32, pl.Float64):
+                try:
+                    col_sum = df[col].sum()
+                    hash_parts.append(f"{col}:{col_sum}")
+                except Exception:
+                    pass
+    hash_input = "|".join(hash_parts).encode()
+    return hashlib.sha256(hash_input).hexdigest()
+@st.cache_data(ttl=300, max_entries=100)
+def _cached_filter_and_collect(
+    _data: pl.LazyFrame,
+    filters_tuple: Tuple[Tuple[str, str], ...],
+    state_tuple: Tuple[Tuple[str, Any], ...],
+    columns_tuple: Optional[Tuple[str, ...]] = None,
+    filter_defaults_tuple: Optional[Tuple[Tuple[str, Any], ...]] = None,
+) -> Tuple[pd.DataFrame, str]:
+    """
+    Filter data and collect with caching.
+    This function is cached by Streamlit, so repeated calls with the same
+    filter state will return cached results without re-executing the query.
+    Returns pandas DataFrame for efficient Arrow serialization to frontend.
+    Args:
+        _data: LazyFrame to filter (underscore prefix tells st.cache_data to hash by id)
+        filters_tuple: Tuple of (identifier, column) pairs from filters dict
+        state_tuple: Tuple of (identifier, value) pairs for current selection state
+            (already has defaults applied from _make_cache_key)
+        columns_tuple: Optional tuple of column names to select (projection)
+        filter_defaults_tuple: Optional tuple of (identifier, default_value) pairs
+            (included for cache key differentiation)
+    Returns:
+        Tuple of (pandas DataFrame, hash string)
+    """
+    data = _data
+    filters = dict(filters_tuple)
+    state = dict(state_tuple)  # Already has defaults applied
+    # Apply column projection FIRST (before filters) for efficiency
+    # This ensures we only read needed columns from disk
+    if columns_tuple:
+        data = data.select(list(columns_tuple))
+    # Apply filters
+    # If ANY filter has no selection (and no default), return empty DataFrame
+    # This prevents loading millions of rows when no spectrum is selected
+    for identifier, column in filters.items():
+        selected_value = state.get(identifier)
+        if selected_value is None:
+            # No selection for this filter - return empty DataFrame
+            # Collect with limit 0 to get schema without data
+            df_polars = data.head(0).collect()
+            data_hash = compute_dataframe_hash(df_polars)
+            df_pandas = df_polars.to_pandas()
+            return (df_pandas, data_hash)
+        # Convert float to int for integer columns to handle JSON number parsing
+        # (JavaScript numbers come back as floats, but Polars Int64 needs int comparison)
+        if isinstance(selected_value, float) and selected_value.is_integer():
+            selected_value = int(selected_value)
+        data = data.filter(pl.col(column) == selected_value)
+    # Collect to Polars DataFrame
+    df_polars = data.collect()
+    # Compute hash efficiently (no pickle)
+    data_hash = compute_dataframe_hash(df_polars)
+    # Convert to pandas for Arrow serialization (zero-copy when possible)
+    df_pandas = df_polars.to_pandas()
+    return (df_pandas, data_hash)
+def filter_and_collect_cached(
+    data: Union[pl.LazyFrame, pl.DataFrame],
+    filters: Dict[str, str],
+    state: Dict[str, Any],
+    columns: Optional[List[str]] = None,
+    filter_defaults: Optional[Dict[str, Any]] = None,
+) -> Tuple[pd.DataFrame, str]:
+    """
+    Filter data based on selection state and collect, with caching.
+    This is the recommended function for components that need filtered data.
+    Results are cached based on filter state, so interactions that don't
+    change the filter values (e.g., clicking within already-filtered data)
+    will return cached results instantly.
+    Returns pandas DataFrame for efficient Arrow serialization to the frontend.
+    The hash is computed efficiently without pickling the data.
+    Args:
+        data: The data to filter (LazyFrame or DataFrame)
+        filters: Mapping of identifier names to column names for filtering
+        state: Current selection state with identifier values
+        columns: Optional list of column names to select (projection pushdown)
+        filter_defaults: Optional default values for filters when state is None.
+            When a filter's state value is None, the default is used instead.
+            Example: {"identification": -1} means None → -1 for identification filter.
+    Returns:
+        Tuple of (pandas DataFrame, hash string) with filters and projection applied
+    """
+    if isinstance(data, pl.DataFrame):
+        data = data.lazy()
+    # Convert to tuples for caching (dicts aren't hashable)
+    filters_tuple = tuple(sorted(filters.items()))
+    # Pass filter_defaults to _make_cache_key so defaults are applied to state
+    state_tuple = _make_cache_key(filters, state, filter_defaults)
+    columns_tuple = tuple(columns) if columns else None
+    filter_defaults_tuple = tuple(sorted(filter_defaults.items())) if filter_defaults else None
+    return _cached_filter_and_collect(
+        data,
+        filters_tuple,
+        state_tuple,
+        columns_tuple,
+        filter_defaults_tuple,
+    )
+def filter_by_selection(
+    data: Union[pl.LazyFrame, pl.DataFrame],
+    interactivity: Dict[str, str],
+    state: Dict[str, Any],
+) -> pl.LazyFrame:
+    """
+    Filter data based on selection state and interactivity mapping.
+    For each identifier in the interactivity mapping, if there's a
+    corresponding selection in state, filter the data to rows where
+    the mapped column equals the selected value.
+    Args:
+        data: The data to filter (LazyFrame or DataFrame)
+        interactivity: Mapping of identifier names to column names
+        state: Current selection state with identifier values
+    Returns:
+        Filtered LazyFrame
+    """
+    if isinstance(data, pl.DataFrame):
+        data = data.lazy()
+    for identifier, column in interactivity.items():
+        selected_value = state.get(identifier)
+        if selected_value is not None:
+            data = data.filter(pl.col(column) == selected_value)
+    return data
+def filter_by_index(
+    data: Union[pl.LazyFrame, pl.DataFrame],
+    index_column: str,
+    index_value: Any,
+) -> pl.LazyFrame:
+    """
+    Filter data to a single row by index value.
+    Args:
+        data: The data to filter
+        index_column: Name of the index column
+        index_value: The index value to filter to
+    Returns:
+        Filtered LazyFrame (typically 1 row)
+    """
+    if isinstance(data, pl.DataFrame):
+        data = data.lazy()
+    return data.filter(pl.col(index_column) == index_value)
+def filter_by_range(
+    data: Union[pl.LazyFrame, pl.DataFrame],
+    x_column: str,
+    y_column: str,
+    x_range: tuple,
+    y_range: tuple,
+) -> pl.LazyFrame:
+    """
+    Filter data within x/y range bounds.
+    Args:
+        data: The data to filter
+        x_column: Name of the x-axis column
+        y_column: Name of the y-axis column
+        x_range: Tuple of (min, max) for x-axis
+        y_range: Tuple of (min, max) for y-axis
+    Returns:
+        Filtered LazyFrame
+    """
+    if isinstance(data, pl.DataFrame):
+        data = data.lazy()
+    return data.filter(
+        (pl.col(x_column) >= x_range[0]) &
+        (pl.col(x_column) <= x_range[1]) &
+        (pl.col(y_column) >= y_range[0]) &
+        (pl.col(y_column) <= y_range[1])
+    )
+def slice_by_row_index(
+    data: Union[pl.LazyFrame, pl.DataFrame],
+    row_index: Optional[int],
+) -> pl.DataFrame:
+    """
+    Slice data to a single row by row position.
+    Args:
+        data: The data to slice
+        row_index: The row index (position) to extract
+    Returns:
+        DataFrame with single row, or empty DataFrame if index is None
+    """
+    if row_index is None:
+        # Return empty DataFrame with same schema
+        if isinstance(data, pl.LazyFrame):
+            return data.head(0).collect()
+        return data.head(0)
+    # For LazyFrames, add slice to query plan before collecting
+    # This allows Polars to optimize and avoid materializing all rows
+    if isinstance(data, pl.LazyFrame):
+        # Note: We can't check bounds without collecting, so we slice optimistically
+        # and return empty if result is empty
+        return data.slice(row_index, 1).collect()
+    # For DataFrames, check bounds first
+    if row_index < 0 or row_index >= len(data):
+        return data.head(0)
+    return data.slice(row_index, 1)