hopscotch-analytics 0.3.0__tar.gz

hopscotch_analytics-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+# Triggered when hopscotch-lib-dev pushes a version tag here
+# after syncing the filtered Python history.
+# Can also be triggered manually via workflow_dispatch.
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    if: ${{ !contains(github.ref, 'rc') }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC Trusted Publisher
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

hopscotch_analytics-0.3.0/CHANGELOG.md

@@ -0,0 +1,130 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+
+## [Unreleased]
+
+## [0.3.0] - 2026-06-21
+
+### Added — Cluster Analysis
+- **`ClusterAnalysis` tool**: KMeans and HDBSCAN clustering with optional NMF
+  decomposition; supports `n_clusters` / `nmf_k` as single value, range
+  (`"3-8"`), or comma-separated list (`"3,5,7"`) for silhouette grid search
+- **`ClusterAnalysisWidget`** (anywidget): interactive sidebar with Configure
+  Features, Configure Metrics, clustering method, scaler, N Clusters, NMF
+  Decomposition fields; heatmap overview, silhouette chart, NMF H/W matrices
+- **Silhouette grid search**: selects best parameter set automatically and
+  highlights it in the bar chart
+
+### Added — Segment Overview
+- **`segment_levels` traitlet**: segment column values available in
+  Configure Metrics `belongs_to` fields without extra round-trips
+- **`active_days` event selector** in Configure Metrics and Configure
+  Features: optional filter to count only days with specific events
+
+### Added — shared metric form components
+- `metric_config_row.tsx`: unified `MetricRow`, `MultiSelect`, `SingleSelect`,
+  `InfoTip`, `validateMetricCfg` shared across Configure Features (CA),
+  Configure Metrics (CA), and Configure Metrics (SO) — ~650 lines removed
+- `showAgg=false` for Configure Features (no aggregation dropdown)
+- All three forms default new rows to `event_count` with all events selected
+- InfoTip on Cluster Analysis sidebar Metrics label explaining overview metrics
+
+### Changed
+- Package renamed from `hopscotch` to `hopscotch-analytics` on PyPI
+- Aggregation global dropdown removed from Cluster Analysis sidebar;
+  aggregation is now configured per-metric in Configure Metrics
+
+### Fixed — Segment Overview
+- `segLevels` ReferenceError crash in metrics overlay
+- `SidebarSH` inline component causing remount and focus loss on
+  Configure Metrics open
+
+### Fixed — Cluster Analysis
+- Default `n_clusters=""` causing KMeans to fail on widget init; now
+  defaults to `"3-8"`
+- NMF K text field losing focus on each keystroke
+
+## [0.2.2] - 2026-06-19
+
+### Fixed
+- `_get_esm()`: fetch widget.js source and return as string to anywidget
+  (anywidget requires inline JS string, not a URL)
+
+## [0.2.1] - 2026-06-19
+
+### Fixed
+- `_get_esm()`: download widget.js to local cache instead of passing URL
+  to anywidget directly
+
+## [0.2.0] - 2026-06-19
+
+
+### Added — Transition Graph
+- **Diff mode node coloring**: nodes tinted red/blue based on event share
+  difference between groups; inner circle radius shrinks proportionally
+  to diff magnitude (zero diff = normal donut, max diff = solid circle)
+- **Node hover tooltip** in diff mode: shows share breakdown per group
+  with subtitle "share of event in group"
+- **Colored dots** (● blue / ● red) next to segment value dropdowns so
+  it's immediately clear which color maps to which group
+- **Fit to canvas** button (expand icon, top-right toolbar) replaces the
+  old Reset Layout button; calls `cy.fit` with 12 px padding
+- **Auto-fit on load**: graph fits the canvas automatically on every
+  render (both auto-layout and saved-positions paths)
+- **Edge Weight Type** label (renamed from "Value Type") in settings sidebar
+
+### Fixed — Transition Graph
+- `value1Label` / `value2Label` falling back to "group1"/"group2" when
+  diff values are boolean `false` — now uses `String()` coercion
+- Diff tooltip label now correctly shows the actual segment value
+
+### Added — Step Sankey
+- **`step_window` parameter**: frontend-only slider in sidebar Visibility
+  Settings (Radix single-thumb slider, amber track); defaults to 3;
+  limits displayed columns per anchor without recomputing backend data
+- **Event Count filter**: sidebar RangeSlider now populated with real
+  `COUNT(DISTINCT path_id)` per event from Python backend;
+  `_populationCustomized` flag prevents reset on recompute
+- **Pattern edit menu** matching platform UX: path_start/path_end show
+  insert panel directly; internal events show Insert Before / Insert
+  After / Replace / Delete first-level menu with Event / Gap+Event tabs
+- `path_start` and `path_end` included in all event dropdowns
+- Diff tooltip label fix (same boolean coercion fix as transition graph)
+
+### Fixed — Step Sankey
+- **Gap+Event for `path_end`** now inserts `event->.*->path_end`
+  (own matrix block) instead of collapsing with existing wildcard
+- **`PatternStore`**: `addWithTrailingGap` method; default display
+  pattern (`path_start->.*->path_end`) no longer leaks into edit state
+  when no real pattern is set — adding events from path_start no longer
+  appends path_end
+- **Column filtering**: end-aligned and start-aligned matrices now
+  correctly limit variable columns on both sides by `stepWindow`
+- **`path_start`/`path_end`** excluded from regular column event nodes
+  (appear only as fixed anchors)
+- **`_find_center_position`**: regex split handles leading/trailing `.*`
+  wildcards — fixes `PatternNoMatchError` for `.*->path_end` patterns
+- **Diff mode** with `.*->path_end`: `original_pattern` passed to sub-
+  calls so `skip_first_matrix` applies correctly in each group
+- **`path_start->.*->path_end`** default no longer shown as a third
+  matrix block when user adds a central event via GUI
+
+### Fixed — Python widget
+- **Save initial widget state** on creation with `object_name` —
+  state is now written synchronously so a subsequent load always
+  restores `path_pattern`, `diff`, etc.
+
+## [0.1.0] - 2026-06-17
+
+### Added
+- `Eventstream` class with DuckDB-powered step matrix and transition matrix
+- `StepSankeyWidget` (anywidget): interactive step sankey with pattern editing,
+  diff mode, segment filters, `max_steps`, persistence via `object_name`
+- `TransitionGraphWidget` (anywidget): Cytoscape.js force-directed graph,
+  edge weight types, diff mode, event count filter, node/edge color picker
+- Supabase OTP authentication paywall baked into bundle at build time
+- GitHub Actions release pipeline: builds JS bundle, creates GitHub Release
+  with `widget.js` asset, syncs Python history to public repo via
+  `git filter-repo`

hopscotch_analytics-0.3.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: hopscotch-analytics
+Version: 0.3.0
+Summary: Clickstream analysis library for Jupyter / Colab / VS Code
+Requires-Python: >=3.11
+Requires-Dist: anywidget>=0.9
+Requires-Dist: duckdb>=1.1
+Requires-Dist: matplotlib>=3.11.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.11
+Requires-Dist: traitlets>=5.0
+Provides-Extra: dev
+Requires-Dist: ipykernel; extra == 'dev'
+Requires-Dist: jupyterlab; extra == 'dev'
+Requires-Dist: notebook; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

hopscotch_analytics-0.3.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hopscotch-analytics"
+version = "0.3.0"
+description = "Clickstream analysis library for Jupyter / Colab / VS Code"
+requires-python = ">=3.11"
+dependencies = [
+    "pandas>=2.2",
+    "duckdb>=1.1",
+    "anywidget>=0.9",
+    "traitlets>=5.0",
+    "pyarrow>=14.0",
+    "scikit-learn>=1.3",
+    "numpy>=1.26",
+    "scipy>=1.11",
+    "matplotlib>=3.11.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov",
+    "ipykernel",
+    "jupyterlab",
+    "notebook",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hopscotch"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.3.0",
+    "jupyterlab>=4.5.8",
+    "pytest>=9.1.0",
+]

hopscotch_analytics-0.3.0/src/hopscotch/__init__.py

@@ -0,0 +1,4 @@
+from hopscotch.eventstream.eventstream import Eventstream
+from hopscotch.eventstream.schema import EventstreamSchema
+
+__all__ = ["Eventstream", "EventstreamSchema"]

hopscotch_analytics-0.3.0/src/hopscotch/data_processors/__init__.py

@@ -0,0 +1,20 @@
+from hopscotch.data_processors.add_clusters import AddClusters
+from hopscotch.data_processors.add_events import AddEvents
+from hopscotch.data_processors.add_segment import AddSegment
+from hopscotch.data_processors.add_start_end_events import AddStartEndEvents
+from hopscotch.data_processors.collapse_events import CollapseEvents
+from hopscotch.data_processors.drop_segment import DropSegment
+from hopscotch.data_processors.edit_events import EditEvents
+from hopscotch.data_processors.filter_events import FilterEvents
+from hopscotch.data_processors.filter_paths import FilterPaths
+from hopscotch.data_processors.rename_events import RenameEvents
+from hopscotch.data_processors.sample_paths import SamplePaths
+from hopscotch.data_processors.split_sessions import SplitSessions
+from hopscotch.data_processors.truncate_paths import TruncatePaths
+from hopscotch.data_processors.url_events import UrlEvents
+
+__all__ = [
+    "AddClusters", "AddEvents", "AddSegment", "AddStartEndEvents", "CollapseEvents", "DropSegment",
+    "EditEvents", "FilterEvents", "FilterPaths", "RenameEvents", "SamplePaths",
+    "SplitSessions", "TruncatePaths", "UrlEvents",
+]

hopscotch_analytics-0.3.0/src/hopscotch/data_processors/add_clusters.py

@@ -0,0 +1,238 @@
+"""
+AddClusters - data processor for clustering trajectories based on metrics.
+
+Clusters trajectories and adds a new segment column with cluster labels.
+Uses MetricBuilder for feature calculation.
+"""
+
+from typing import Any, Dict, List, Literal, Tuple
+
+import numpy as np
+import pandas as pd
+from sklearn.cluster import HDBSCAN, KMeans
+from sklearn.decomposition import NMF
+from sklearn.preprocessing import MinMaxScaler, StandardScaler
+
+from hopscotch.data_processors.data_processor import DataProcessor
+from hopscotch.eventstream.schema import EventstreamSchema
+from hopscotch.exceptions import PreprocessingConfigError
+from hopscotch.metrics.metric_builder import MetricBuilder
+
+PROCESSOR_NAME = "add_clusters"
+
+T_ClusteringMethod = Literal["kmeans", "hdbscan"]
+T_Scaler = Literal["minmax", "std"] | None
+
+
+class AddClusters(DataProcessor):
+    """
+    Data processor that clusters trajectories based on computed metrics.
+
+    Adds a new segment column containing cluster labels for each trajectory.
+
+    Attributes:
+        segment_name: Name of the new segment column
+        metrics: List of metric configurations (MetricBuilder format)
+        method: Clustering method ("kmeans" or "hdbscan")
+        scaler: Feature scaler method ("minmax", "std", or None)
+        method_params: Parameters for the clustering algorithm
+        eventstream: Eventstream instance (needed for MetricBuilder)
+        path_id_col: Path ID column name (optional)
+        event_col: Event column name (optional)
+    """
+
+    segment_name: str
+    metrics: List[Dict[str, Any]]
+    method: T_ClusteringMethod
+    scaler: T_Scaler
+    method_params: Dict[str, Any]
+    nmf_k: int | None
+    eventstream: Any
+    path_id_col: str | None
+    event_col: str | None
+
+    def __init__(
+        self,
+        eventstream: Any,
+        segment_name: str,
+        metrics: List[Dict[str, Any]],
+        method: T_ClusteringMethod = "kmeans",
+        scaler: T_Scaler = "minmax",
+        n_clusters: int | None = None,
+        min_cluster_size: int | None = None,
+        cluster_selection_epsilon: float | None = None,
+        nmf_k: int | None = None,
+        path_id_col: str | None = None,
+        event_col: str | None = None,
+    ) -> None:
+        """
+        Initialize AddClusters processor.
+
+        Args:
+            eventstream: Eventstream instance for metric calculation
+            segment_name: Name of the new segment column with cluster labels
+            metrics: List of metric configurations for MetricBuilder.
+                     Each config is a dict with 'metric' and optional 'metric_args'.
+                     Example: [
+                         {"metric": "length"},
+                         {"metric": "duration"},
+                         {"metric": "event_count", "metric_args": {"event": "purchase"}}
+                     ]
+            method: Clustering method - "kmeans" or "hdbscan"
+            scaler: Feature scaler - "minmax", "std", or None.
+                    Default is "minmax".
+            n_clusters: Number of clusters for k-means (required for kmeans)
+            min_cluster_size: Minimum cluster size for HDBSCAN
+            cluster_selection_epsilon: Cluster selection epsilon for HDBSCAN
+            path_id_col: Path ID column (if None, taken from schema)
+            event_col: Event column (if None, taken from schema)
+        """
+        self.eventstream = eventstream
+        self.segment_name = segment_name
+        self.metrics = metrics
+        self.method = method
+        self.scaler = scaler
+        self.nmf_k = nmf_k
+        self.path_id_col = path_id_col
+        self.event_col = event_col
+
+        # Validate method and collect method-specific parameters
+        if method == "kmeans":
+            if n_clusters is None:
+                raise PreprocessingConfigError(PROCESSOR_NAME, "n_clusters is required for kmeans method")
+            self.method_params = {"n_clusters": n_clusters}
+        elif method == "hdbscan":
+            self.method_params = {}
+            if min_cluster_size is not None:
+                self.method_params["min_cluster_size"] = min_cluster_size
+            if cluster_selection_epsilon is not None:
+                self.method_params["cluster_selection_epsilon"] = cluster_selection_epsilon
+        else:
+            raise PreprocessingConfigError(PROCESSOR_NAME, f"Unknown clustering method: {method}. Use 'kmeans' or 'hdbscan'.")
+
+        super().__init__()
+
+    def apply(
+        self, df: pd.DataFrame, schema: EventstreamSchema
+    ) -> Tuple[pd.DataFrame, EventstreamSchema]:
+        """
+        Apply clustering to trajectories and add cluster labels as a new segment.
+
+        Args:
+            df: Input DataFrame with eventstream data
+            schema: EventstreamSchema with column definitions
+
+        Returns:
+            Tuple of (new_df, new_schema) with added cluster segment
+        """
+        # Validate segment name doesn't exist
+        if self.segment_name in df.columns:
+            if self.segment_name in schema.segment_cols:
+                raise PreprocessingConfigError(PROCESSOR_NAME, f"Segment '{self.segment_name}' already exists.")
+            else:
+                raise PreprocessingConfigError(
+                    PROCESSOR_NAME,
+                    f"Name '{self.segment_name}' is already reserved in the eventstream."
+                )
+
+        path_id_col = self.path_id_col or schema.path_col
+        event_col = self.event_col or schema.event_col  # noqa: F841 - reserved for future use
+
+        # Build metrics using MetricBuilder
+        metric_builder = MetricBuilder(self.eventstream)
+        metrics_df = metric_builder.build_metrics(self.metrics, path_id_col)
+
+        if metrics_df.empty:
+            raise PreprocessingConfigError(PROCESSOR_NAME, "No metrics were computed. Check metric configurations.")
+
+        # Handle NaN values - fill with 0 for clustering
+        features = metrics_df.fillna(0).values
+
+        if features.shape[1] == 0:
+            raise PreprocessingConfigError(PROCESSOR_NAME, "No feature columns were generated from metrics.")
+
+        # Apply scaling
+        features_scaled = self._scale_features(features)
+
+        # Apply NMF dimensionality reduction if requested
+        if self.nmf_k is not None:
+            nmf = NMF(n_components=self.nmf_k, random_state=42)
+            features_scaled = nmf.fit_transform(features_scaled)
+
+        # Perform clustering
+        cluster_labels = self._cluster(features_scaled)
+
+        # Create cluster labels Series indexed by path_id
+        cluster_series = pd.Series(
+            cluster_labels,
+            index=metrics_df.index,
+            name=self.segment_name
+        )
+
+        # Convert labels to string for categorical representation
+        # HDBSCAN uses -1 for noise points, handle specially
+        cluster_series = cluster_series.apply(
+            lambda x: f"cluster_{x}" if x >= 0 else "noise"
+        )
+
+        # Map cluster labels to all events in the dataframe
+        new_df = df.copy()
+        new_df[self.segment_name] = new_df[path_id_col].map(cluster_series)
+        new_df[self.segment_name] = new_df[self.segment_name].astype("category")
+
+        # Update schema
+        new_schema = schema.copy()
+        new_schema.segment_cols.append(self.segment_name)
+
+        return new_df, new_schema
+
+    def _scale_features(self, features: np.ndarray) -> np.ndarray:
+        """
+        Scale features based on the configured method.
+
+        Args:
+            features: Raw feature matrix
+
+        Returns:
+            Scaled feature matrix
+        """
+        if self.scaler is None:
+            return features
+        elif self.scaler == "minmax":
+            scaler = MinMaxScaler()
+            return scaler.fit_transform(features)
+        elif self.scaler == "std":
+            scaler = StandardScaler()
+            return scaler.fit_transform(features)
+        else:
+            raise PreprocessingConfigError(PROCESSOR_NAME, f"Unknown scaler method: {self.scaler}")
+
+    def _cluster(self, features: np.ndarray) -> np.ndarray:
+        """
+        Perform clustering using the configured method.
+
+        Args:
+            features: Standardized feature matrix
+
+        Returns:
+            Array of cluster labels
+        """
+        if self.method == "kmeans":
+            clusterer = KMeans(
+                n_clusters=self.method_params["n_clusters"],
+                random_state=42,
+                n_init="auto"
+            )
+            return clusterer.fit_predict(features)
+        elif self.method == "hdbscan":
+            # Set defaults for HDBSCAN if not provided
+            min_cluster_size = self.method_params.get("min_cluster_size", 5)
+            cluster_selection_epsilon = self.method_params.get("cluster_selection_epsilon", 0.0)
+
+            clusterer = HDBSCAN(
+                min_cluster_size=min_cluster_size,
+                cluster_selection_epsilon=cluster_selection_epsilon
+            )
+            return clusterer.fit_predict(features)
+        else:
+            raise PreprocessingConfigError(PROCESSOR_NAME, f"Unknown clustering method: {self.method}")

hopscotch_analytics-0.3.0/src/hopscotch/data_processors/add_events.py

@@ -0,0 +1,159 @@
+from typing import List, Tuple
+
+import duckdb
+import pandas as pd
+
+from hopscotch.data_processors.data_processor import DataProcessor
+from hopscotch.eventstream.event_type import EventTypes
+from hopscotch.eventstream.schema import EventstreamSchema
+from hopscotch.exceptions import PreprocessingConfigError
+
+PROCESSOR_NAME = "add_events"
+
+
+class AddEvents(DataProcessor):
+
+    def __init__(
+        self,
+        new_event_name: str,
+        source_events: List[str] | None = None,
+        sql: str | None = None,
+        churn: dict | None = None,
+    ) -> None:
+        if not isinstance(new_event_name, str) or not new_event_name:
+            raise PreprocessingConfigError(PROCESSOR_NAME, "Argument 'new_event_name' must be a non-empty string.")
+
+        n_modes = sum([source_events is not None, sql is not None, churn is not None])
+        if n_modes != 1:
+            raise PreprocessingConfigError(
+                PROCESSOR_NAME,
+                "Exactly one of 'source_events', 'sql', or 'churn' must be provided."
+            )
+
+        if source_events is not None:
+            if not isinstance(source_events, list):
+                raise PreprocessingConfigError(PROCESSOR_NAME, "Argument 'source_events' must be a list.")
+            if not all(isinstance(e, str) for e in source_events):
+                raise PreprocessingConfigError(PROCESSOR_NAME, "All elements in 'source_events' must be strings.")
+
+        if sql is not None and not isinstance(sql, str):
+            raise PreprocessingConfigError(PROCESSOR_NAME, "Argument 'sql' must be a string.")
+
+        if churn is not None:
+            if not isinstance(churn, dict):
+                raise PreprocessingConfigError(PROCESSOR_NAME, "Argument 'churn' must be a dictionary.")
+            if "inactivity_days" not in churn:
+                raise PreprocessingConfigError(PROCESSOR_NAME, "Argument 'churn' must contain 'inactivity_days'.")
+            inactivity_days = churn["inactivity_days"]
+            if not isinstance(inactivity_days, (int, float)) or inactivity_days <= 0:
+                raise PreprocessingConfigError(
+                    PROCESSOR_NAME, "Value 'churn.inactivity_days' must be a positive number."
+                )
+            active_events = churn.get("active_events")
+            if active_events is not None:
+                if not isinstance(active_events, list):
+                    raise PreprocessingConfigError(
+                        PROCESSOR_NAME, "Value 'churn.active_events' must be a list."
+                    )
+                if not all(isinstance(e, str) for e in active_events):
+                    raise PreprocessingConfigError(
+                        PROCESSOR_NAME, "All elements in 'churn.active_events' must be strings."
+                    )
+
+        self.new_event_name = new_event_name
+        self.source_events = source_events
+        self.sql = sql
+        self.churn = churn
+        super().__init__()
+
+    def apply(
+        self, df: pd.DataFrame, schema: EventstreamSchema
+    ) -> Tuple[pd.DataFrame, EventstreamSchema]:
+        if self.source_events is not None:
+            df_source = self._get_by_source_events(df, schema)
+        elif self.sql is not None:
+            df_source = self._get_by_sql(df, schema)
+        else:
+            df_source = self._get_by_churn(df, schema)
+
+        if df_source.empty:
+            return df, schema
+
+        event_types = EventTypes()
+        df_new = df_source.copy()
+        df_new[schema.event_col] = self.new_event_name
+        df_new[schema.event_type] = event_types.SYNTHETIC_EVENT.type
+        df_new[schema.subindex] = event_types.SYNTHETIC_EVENT.index
+
+        df = (
+            pd.concat([df, df_new])
+            .sort_values([schema.path_col, schema.timestamp, schema.subindex])
+            .reset_index(drop=True)
+        )
+
+        df[schema.event_col] = df[schema.event_col].astype("category")
+
+        return df, schema
+
+    def _get_by_source_events(self, df: pd.DataFrame, schema: EventstreamSchema) -> pd.DataFrame:
+        if not self.source_events:
+            return df.iloc[0:0]
+
+        existing = set(df[schema.event_col].cat.categories.tolist())
+        unknown = set(self.source_events) - existing
+        if unknown:
+            raise PreprocessingConfigError(
+                PROCESSOR_NAME,
+                f"Unknown event names in 'source_events': {sorted(unknown)}. "
+                f"Available events: {sorted(existing)}."
+            )
+
+        return df[df[schema.event_col].isin(self.source_events)].copy()
+
+    def _get_by_sql(self, df: pd.DataFrame, schema: EventstreamSchema) -> pd.DataFrame:
+        columns_old = set(df.columns)
+        eventstream = df  # noqa: F841  — referenced by user SQL as "eventstream"
+        result = duckdb.sql(self.sql).df()
+        if set(result.columns) != columns_old:
+            raise PreprocessingConfigError(
+                PROCESSOR_NAME,
+                "The SQL query must return the same columns as the eventstream."
+            )
+        return result
+
+    def _get_by_churn(self, df: pd.DataFrame, schema: EventstreamSchema) -> pd.DataFrame:
+        path_col = schema.path_col
+        ts_col = schema.timestamp
+        subindex_col = schema.subindex
+        event_col = schema.event_col
+
+        inactivity_days = self.churn["inactivity_days"]
+        active_events = self.churn.get("active_events")
+
+        threshold_seconds = inactivity_days * 86400
+
+        # Filter to active events only if specified; otherwise all events count.
+        # LEAD looks only within the filtered set, so the "next active event"
+        # is found correctly. The overall dataset max comes from the full df.
+        active_filter = ""
+        if active_events is not None:
+            if not active_events:
+                return df.iloc[0:0]
+            quoted = ", ".join(f"'{e}'" for e in active_events)
+            active_filter = f"WHERE {event_col} IN ({quoted})"
+
+        query = f"""
+            WITH windowed AS (
+                SELECT *,
+                    LEAD({ts_col}) OVER (
+                        PARTITION BY {path_col} ORDER BY {ts_col}, {subindex_col}
+                    ) AS _hop_next_ts,
+                    (SELECT MAX({ts_col}) FROM df) AS _hop_dataset_end
+                FROM df
+                {active_filter}
+            )
+            SELECT * EXCLUDE (_hop_next_ts, _hop_dataset_end) FROM windowed
+            WHERE epoch(COALESCE(_hop_next_ts, _hop_dataset_end)) - epoch({ts_col})
+                  > {threshold_seconds}
+        """
+        return duckdb.sql(query).df()