openms-insight 0.1.0__py3-none-any.whl

openms_insight/rendering/__init__.py

@@ -0,0 +1,8 @@
+"""Rendering utilities for Python-to-Vue communication."""
+
+from .bridge import render_component, get_vue_component_function
+
+__all__ = [
+    "render_component",
+    "get_vue_component_function",
+]

openms_insight/rendering/bridge.py

@@ -0,0 +1,312 @@
+"""Bridge between Python components and Vue frontend."""
+
+import hashlib
+import json
+import os
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
+
+import pandas as pd
+import polars as pl
+import streamlit as st
+
+
+def _make_hashable(value: Any) -> Any:
+    """
+    Convert a value to a hashable form for use in cache keys.
+
+    Handles dicts and lists by converting to JSON strings.
+
+    Args:
+        value: Any value from state
+
+    Returns:
+        A hashable version of the value
+    """
+    if isinstance(value, dict):
+        # Convert dict to sorted JSON string for consistent hashing
+        return json.dumps(value, sort_keys=True)
+    if isinstance(value, list):
+        return json.dumps(value)
+    return value
+
+if TYPE_CHECKING:
+    from ..core.base import BaseComponent
+    from ..core.state import StateManager
+
+
+# Cache the Vue component function
+_vue_component_func = None
+
+# Session state key for Vue's echoed hash (what Vue currently has)
+# Used for bidirectional hash confirmation - we only send data when
+# Vue's echoed hash doesn't match the current data hash
+_VUE_ECHOED_HASH_KEY = "_svc_vue_echoed_hashes"
+
+
+
+@st.cache_data(max_entries=10, show_spinner=False)
+def _cached_prepare_vue_data(
+    _component: 'BaseComponent',
+    component_id: str,
+    filter_state_hashable: Tuple[Tuple[str, Any], ...],
+    _data_id: int,
+    _state_dict: Dict[str, Any],
+) -> Tuple[Dict[str, Any], str]:
+    """
+    Cached wrapper for _prepare_vue_data.
+
+    Cache key is based on:
+    - component_id: unique key for this component instance
+    - filter_state_hashable: hashable version of state values (for cache key only)
+
+    The _component, _data_id, and _state_dict parameters are prefixed with underscore
+    so they are not hashed (component instances are not hashable, and state_dict
+    may contain unhashable values like dicts).
+
+    Args:
+        _component: The component to prepare data for (not hashed)
+        component_id: Unique identifier for this component
+        filter_state_hashable: Tuple of (identifier, hashable_value) for cache key
+        _data_id: id() of the raw data object (not used in cache key)
+        _state_dict: Original state dict with actual values (not hashed)
+
+    Returns:
+        Tuple of (vue_data dict, data_hash string)
+    """
+    # Use the original state dict (not the hashable version)
+    vue_data = _component._prepare_vue_data(_state_dict)
+
+    # Compute hash before any conversion
+    data_hash = _hash_data(vue_data)
+
+    return vue_data, data_hash
+
+
+def get_vue_component_function():
+    """
+    Get the Streamlit component function for the Vue frontend.
+
+    Returns:
+        The declared Streamlit component function
+    """
+    global _vue_component_func
+
+    if _vue_component_func is None:
+        import streamlit.components.v1 as st_components
+
+        # Check for development mode
+        dev_mode = os.environ.get('SVC_DEV_MODE', 'false').lower() == 'true'
+
+        if dev_mode:
+            # Development mode: connect to Vite dev server
+            dev_url = os.environ.get('SVC_DEV_URL', 'http://localhost:5173')
+            _vue_component_func = st_components.declare_component(
+                "streamlit_vue_component",
+                url=dev_url,
+            )
+        else:
+            # Production mode: use built component
+            parent_dir = os.path.dirname(os.path.abspath(__file__))
+            build_dir = os.path.join(parent_dir, '..', 'js-component', 'dist')
+
+            if not os.path.exists(build_dir):
+                raise RuntimeError(
+                    f"Vue component build not found at {build_dir}. "
+                    "Please build the Vue component or set SVC_DEV_MODE=true "
+                    "for development."
+                )
+
+            _vue_component_func = st_components.declare_component(
+                "streamlit_vue_component",
+                path=build_dir,
+            )
+
+    return _vue_component_func
+
+
+def render_component(
+    component: 'BaseComponent',
+    state_manager: 'StateManager',
+    key: Optional[str] = None,
+    height: Optional[int] = None,
+) -> Any:
+    """
+    Render a component in Streamlit.
+
+    This function:
+    1. Gets current state from StateManager
+    2. Calls component._prepare_vue_data() to get filtered data (cached!)
+    3. Computes hash for change detection
+    4. Only sends data if hash changed from last render (optimization)
+    5. Calls the Vue component with data payload
+    6. Updates StateManager from Vue response
+    7. Triggers st.rerun() if state changed
+
+    Args:
+        component: The component to render
+        state_manager: StateManager for cross-component state
+        key: Optional unique key for the Streamlit component
+        height: Optional height in pixels
+
+    Returns:
+        The value returned by the Vue component
+    """
+    # Get current state
+    state = state_manager.get_state_for_vue()
+
+    # Generate unique key if not provided (needed for cache)
+    # Use cache_id instead of id(component) since components are recreated each rerun
+    if key is None:
+        key = f"svc_{component._cache_id}_{hash(str(component._interactivity))}"
+
+    # Extract state keys that affect this component's data for cache key
+    # This includes filters and any additional dependencies (e.g., zoom for heatmaps)
+    # Uses get_state_dependencies() which can be overridden by subclasses
+    state_keys = set(component.get_state_dependencies())
+
+    # Build hashable version for cache key (converts dicts/lists to JSON strings)
+    filter_state_hashable = tuple(sorted(
+        (k, _make_hashable(state.get(k))) for k in state_keys
+    ))
+
+    # Build original state dict for passing to _prepare_vue_data
+    # (contains actual values, not JSON strings)
+    relevant_state = {k: state.get(k) for k in state_keys}
+
+    # Build component ID for cache (includes type to avoid collisions)
+    component_type = component._get_vue_component_name()
+    component_id = f"{component_type}:{key}"
+
+    # Get data identity - cache invalidates if raw data object changes
+    data_id = id(component._raw_data)
+
+    # Get component data using cached function
+    # Cache key: (component_id, filter_state_hashable, data_id)
+    # - Filterless components: filter_state=() always → always cache hit
+    # - Filtered components: cache hit when filter values unchanged
+    vue_data, data_hash = _cached_prepare_vue_data(
+        component, component_id, filter_state_hashable, data_id, relevant_state
+    )
+
+    component_args = component._get_component_args()
+
+    # Initialize hash cache in session state if needed
+    if _VUE_ECHOED_HASH_KEY not in st.session_state:
+        st.session_state[_VUE_ECHOED_HASH_KEY] = {}
+
+    # Hash tracking key includes filter state so different filter values have separate tracking
+    # This ensures data is re-sent when filters change (e.g., different spectrum selected)
+    hash_tracking_key = f"{key}:{filter_state_hashable}"
+
+    # Get Vue's last-echoed hash for this component + filter state
+    # This is what Vue reported having in its last response for this exact filter state
+    vue_echoed_hash = st.session_state[_VUE_ECHOED_HASH_KEY].get(hash_tracking_key)
+
+    # Send data if Vue's hash doesn't match current hash
+    # This handles: first render, data change, browser refresh, Vue hot reload
+    # Vue echoes null/None if it has no data, so mismatch triggers send
+    # IMPORTANT: Also send data if vue_echoed_hash is None - this means Vue
+    # hasn't confirmed receipt yet (e.g., after page navigation destroys Vue component)
+    data_changed = (vue_echoed_hash is None) or (vue_echoed_hash != data_hash)
+
+    # Only include full data if hash changed
+    if data_changed:
+        # Convert any non-pandas data to pandas for Arrow serialization
+        # pandas DataFrames are passed through (already optimal for Arrow)
+        # Also filter out internal keys (starting with _)
+        converted_data = {}
+        for data_key, value in vue_data.items():
+            if data_key.startswith('_'):
+                # Skip metadata keys like _hash, _plotConfig
+                continue
+            if isinstance(value, pl.LazyFrame):
+                converted_data[data_key] = value.collect().to_pandas()
+            elif isinstance(value, pl.DataFrame):
+                converted_data[data_key] = value.to_pandas()
+            else:
+                converted_data[data_key] = value
+            # pandas DataFrames pass through unchanged (optimal for Arrow)
+        data_payload = {
+            **converted_data,
+            'selection_store': state,
+            'hash': data_hash,
+            'dataChanged': True,
+        }
+        # Note: We don't pre-set the hash here anymore. We trust Vue's echo
+        # at the end of the render cycle. This ensures we detect when Vue
+        # loses its data (e.g., page navigation) and needs it resent.
+    else:
+        # Data unchanged - only send hash and state, Vue will use cached data
+        data_payload = {
+            'selection_store': state,
+            'hash': data_hash,
+            'dataChanged': False,
+        }
+
+    # Add height to component args if specified
+    if height is not None:
+        component_args['height'] = height
+
+    # Component layout: [[{componentArgs: {...}}]]
+    components = [[{'componentArgs': component_args}]]
+
+    # Call Vue component
+    vue_func = get_vue_component_function()
+
+    kwargs = {
+        'components': components,
+        'key': key,
+        **data_payload,
+    }
+    if height is not None:
+        kwargs['height'] = height
+
+    result = vue_func(**kwargs)
+
+    # 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
+        vue_hash = result.get('_vueDataHash')
+        st.session_state[_VUE_ECHOED_HASH_KEY][hash_tracking_key] = vue_hash
+
+        # Update state and rerun if state changed
+        if state_manager.update_from_vue(result):
+            st.rerun()
+
+    return result
+
+
+def _hash_data(data: Dict[str, Any]) -> str:
+    """
+    Compute hash of data payload for change detection.
+
+    Uses efficient hashing based on shape and samples for DataFrames,
+    avoiding full data serialization.
+
+    Args:
+        data: The data dict to hash
+
+    Returns:
+        SHA256 hash string
+    """
+    from ..preprocessing.filtering import compute_dataframe_hash
+
+    hash_parts = []
+    for key, value in sorted(data.items()):
+        if key.startswith('_'):
+            continue  # Skip metadata
+        if isinstance(value, pd.DataFrame):
+            # Efficient hash for DataFrames
+            df_polars = pl.from_pandas(value)
+            hash_parts.append(f"{key}:{compute_dataframe_hash(df_polars)}")
+        elif isinstance(value, pl.DataFrame):
+            hash_parts.append(f"{key}:{compute_dataframe_hash(value)}")
+        elif isinstance(value, (list, dict)):
+            # For small data, use string repr
+            hash_parts.append(f"{key}:{hash(str(value)[:1000])}")
+        else:
+            hash_parts.append(f"{key}:{hash(str(value))}")
+
+    return hashlib.sha256("|".join(hash_parts).encode()).hexdigest()

openms_insight-0.1.0.dist-info/METADATA

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: openms-insight
+Version: 0.1.0
+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
+Project-URL: Repository, https://github.com/t0mdavid-m/OpenMS-Insight
+Project-URL: Issues, https://github.com/t0mdavid-m/OpenMS-Insight/issues
+Author: Kohlbacher Lab
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: mass-spectrometry,openms,plotly,proteomics,streamlit,tabulator,visualization,vue
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: polars>=0.19.0
+Requires-Dist: streamlit>=1.20.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OpenMS-Insight
+
+[![PyPI version](https://badge.fury.io/py/openms-insight.svg)](https://badge.fury.io/py/openms-insight)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+Interactive visualization components for mass spectrometry data in Streamlit, backed by Vue.js.
+
+## Features
+
+- **Cross-component selection linking** via shared identifiers
+- **Polars LazyFrame support** for efficient data handling
+- **Automatic disk caching** with config-based invalidation
+- **Table component** (Tabulator.js) with filtering, sorting, go-to, pagination
+- **Line plot component** (Plotly.js) with highlighting, annotations, zoom
+- **Heatmap component** (Plotly scattergl) with multi-resolution downsampling
+- **Sequence view component** for peptide/protein visualization
+
+## Installation
+
+```bash
+pip install openms-insight
+```
+
+## Quick Start
+
+```python
+import streamlit as st
+import polars as pl
+from openms_insight import Table, LinePlot, StateManager
+
+# Create state manager for cross-component linking
+state_manager = StateManager()
+
+# Create a table - clicking a row sets the 'item' selection
+table = Table(
+    cache_id="items_table",
+    data=pl.scan_parquet("items.parquet"),
+    interactivity={'item': 'item_id'},
+    column_definitions=[
+        {'field': 'item_id', 'title': 'ID', 'sorter': 'number'},
+        {'field': 'name', 'title': 'Name'},
+    ],
+)
+table(state_manager=state_manager)
+
+# Create a linked plot - filters by the selected 'item'
+plot = LinePlot(
+    cache_id="values_plot",
+    data=pl.scan_parquet("values.parquet"),
+    filters={'item': 'item_id'},
+    x_column='x',
+    y_column='y',
+)
+plot(state_manager=state_manager)
+```
+
+## Cross-Component Linking
+
+Components communicate through **identifiers** using two mechanisms:
+
+- **`filters`**: INPUT - filter this component's data by the selection
+- **`interactivity`**: OUTPUT - set a selection when user clicks
+
+```python
+# Master table: no filters, sets 'spectrum' on click
+master = Table(
+    cache_id="spectra",
+    data=spectra_data,
+    interactivity={'spectrum': 'scan_id'},  # Click -> sets spectrum=scan_id
+)
+
+# Detail table: filters by 'spectrum', sets 'peak' on click
+detail = Table(
+    cache_id="peaks",
+    data=peaks_data,
+    filters={'spectrum': 'scan_id'},        # Filters where scan_id = selected spectrum
+    interactivity={'peak': 'peak_id'},      # Click -> sets peak=peak_id
+)
+
+# Plot: filters by 'spectrum', highlights selected 'peak'
+plot = LinePlot(
+    cache_id="plot",
+    data=peaks_data,
+    filters={'spectrum': 'scan_id'},
+    interactivity={'peak': 'peak_id'},
+    x_column='mass',
+    y_column='intensity',
+)
+```
+
+---
+
+## Components
+
+### Table
+
+Interactive table using Tabulator.js with filtering dialogs, sorting, pagination, and CSV export.
+
+```python
+Table(
+    cache_id="spectra_table",
+    data=pl.scan_parquet("spectra.parquet"),
+    interactivity={'spectrum': 'scan_id'},
+    column_definitions=[
+        {'field': 'scan_id', 'title': 'Scan', 'sorter': 'number'},
+        {'field': 'rt', 'title': 'RT (min)', 'sorter': 'number', 'hozAlign': 'right'},
+        {'field': 'precursor_mz', 'title': 'm/z', 'sorter': 'number'},
+    ],
+    index_field='scan_id',
+    go_to_fields=['scan_id'],
+    default_row=0,
+    pagination=True,
+    page_size=50,
+)
+```
+
+### LinePlot
+
+Stick-style line plot using Plotly.js for mass spectra visualization.
+
+```python
+LinePlot(
+    cache_id="spectrum_plot",
+    data=pl.scan_parquet("peaks.parquet"),
+    filters={'spectrum': 'scan_id'},
+    interactivity={'peak': 'peak_id'},
+    x_column='mass',
+    y_column='intensity',
+    highlight_column='is_annotated',
+    annotation_column='ion_label',
+    title="MS/MS Spectrum",
+    x_label="m/z",
+    y_label="Intensity",
+)
+```
+
+### Heatmap
+
+2D scatter heatmap using Plotly scattergl with multi-resolution downsampling for large datasets (millions of points).
+
+```python
+Heatmap(
+    cache_id="peaks_heatmap",
+    data=pl.scan_parquet("all_peaks.parquet"),
+    x_column='retention_time',
+    y_column='mass',
+    intensity_column='intensity',
+    interactivity={'spectrum': 'scan_id', 'peak': 'peak_id'},
+    min_points=30000,
+    title="Peak Map",
+    x_label="Retention Time (min)",
+    y_label="m/z",
+)
+```
+
+### SequenceView
+
+Peptide/protein sequence visualization with fragment ion matching.
+
+```python
+SequenceView(
+    cache_id="peptide_view",
+    sequence="PEPTIDEK",
+    observed_masses=[147.1, 244.2, 359.3, 456.4],
+    peak_ids=[0, 1, 2, 3],
+    precursor_mass=944.5,
+    interactivity={'peak': 'peak_id'},
+    title="Fragment Coverage",
+)
+```
+
+---
+
+## Shared Component Arguments
+
+All components accept these common arguments:
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `cache_id` | `str` | **Required** | Unique identifier for disk cache |
+| `data` | `pl.LazyFrame` | `None` | Polars LazyFrame with source data |
+| `filters` | `Dict[str, str]` | `None` | Map identifier -> column for filtering |
+| `interactivity` | `Dict[str, str]` | `None` | Map identifier -> column for click actions |
+| `cache_path` | `str` | `"."` | Base directory for cache storage |
+
+## Rendering
+
+All components are callable. Pass a `StateManager` to enable cross-component linking:
+
+```python
+from openms_insight import StateManager
+
+state_manager = StateManager()
+
+table(state_manager=state_manager, height=300)
+plot(state_manager=state_manager, height=400)
+```
+
+---
+
+## Development
+
+### Building the Vue Component
+
+```bash
+cd js-component
+npm install
+npm run build
+```
+
+### Development Mode
+
+```bash
+cd js-component
+npm run dev
+
+# In another terminal:
+export SVC_DEV_MODE=true
+export SVC_DEV_URL=http://localhost:5173
+streamlit run app.py
+```

openms_insight-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+openms_insight/__init__.py,sha256=-QMPUfCk1DwwlQKW6NFSZodRz-r82R4rJPOiWDf_mwA,830
+openms_insight/components/__init__.py,sha256=aNy1E8ttqQiiA5Ka9sviRy17gQT8lfc_EHsl1v1o-UQ,177
+openms_insight/components/heatmap.py,sha256=wqNgmccxI5PeTC08kVf06UUtVEg8YhUf_eY9CN4wAMw,33125
+openms_insight/components/lineplot.py,sha256=klGzpGO-gi76sIocr9T4TYUTV-ztfIIAtdd5k-U-aGE,19382
+openms_insight/components/sequenceview.py,sha256=IPLyUiXTLYwdZ79B3pZDH1intUsjBIknTSLUQ2ftdD4,14359
+openms_insight/components/table.py,sha256=VaUbn2lckeT3shqn9quDvw1HGMsiQrIPPK4w1XQFzzc,14795
+openms_insight/core/__init__.py,sha256=yKRgLfRm1CQm6ZGqQiyDwblzw2Qh3jw57U-ZSd63PYk,338
+openms_insight/core/base.py,sha256=e939N2cu0TEllj09Uw7AKS0FqxE2n_XecwF3ckM_YM0,14746
+openms_insight/core/cache.py,sha256=3fnPDWjuWUnxazK2XflcUIeRZZPQ3N45kAKYu-xGBKw,1197
+openms_insight/core/registry.py,sha256=iBb9xWvgOisxjVX74wtCvqWO20eBW5xH-XcNcVuW-Dg,2107
+openms_insight/core/state.py,sha256=VhY_3Yg-zbx9VsdqHElsNyD2UbJj6ApE4TRcUywDrjQ,6871
+openms_insight/preprocessing/__init__.py,sha256=XFnxlvG-VRMrFbreGmFSIDqfYhev8WPUyZluadMmCgY,462
+openms_insight/preprocessing/compression.py,sha256=8oe-vqeSX-Xf1okPX0C0km2DRnl6Iz53Y1UgsLdMUPI,10499
+openms_insight/preprocessing/filtering.py,sha256=chvmCqLLsMe5mXwG_S4KUagNqJZFLI_iLKKr9g-MkLM,10907
+openms_insight/rendering/__init__.py,sha256=i9MRFrAEAX5kjbOnMjw2woP_6mEaI6HcxtbrNwUxNaM,198
+openms_insight/rendering/bridge.py,sha256=yzXPyK_oKVGBymeDWxgzXeI_jOP7ntJ4p_npOQ1-d1A,11279
+openms_insight/js-component/dist/index.html,sha256=LSJ3B_YmGUrCCdZ1UaZO2p6Wqsih6nTH62Z_0uZxpD8,430
+openms_insight/js-component/dist/assets/index.css,sha256=h0LrX503uebeJrJB0LtoPCVwA4QfDBMmOOR_tU2Wkic,883995
+openms_insight/js-component/dist/assets/index.js,sha256=pakZe7BdeEjiDCPhzGYqEFumB3WtbdnnXYnBuTDVfWo,6060653
+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.0.dist-info/METADATA,sha256=S7rH1PAk9nJDomrQSDnJFmiGC7v8JcwnfrGcBqe55iM,7288
+openms_insight-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openms_insight-0.1.0.dist-info/licenses/LICENSE,sha256=INFF4rOMmpah7Oi14hLqu7NTOsx56KRRNChAAUcfh2E,1823
+openms_insight-0.1.0.dist-info/RECORD,,

openms_insight-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

openms_insight-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+--------------------------------------------------------------------------
+                  OpenMS -- Open-Source Mass Spectrometry
+--------------------------------------------------------------------------
+Copyright OpenMS Inc. -- Eberhard Karls University Tuebingen,
+ETH Zurich, and Freie Universitaet Berlin 2002-present.
+
+This software is released under a three-clause BSD license:
+ * Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+ * Neither the name of any author or any participating institution
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+For a full list of authors, refer to the git contributions.
+--------------------------------------------------------------------------
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL ANY OF THE AUTHORS OR THE CONTRIBUTING
+INSTITUTIONS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+