sublimex 0.1.0__py3-none-any.whl

sublimex/__init__.py

@@ -0,0 +1,22 @@
+"""SublimeX: Supervised Bottom-Up Localized Multi-Representative Feature Extraction."""
+
+__version__ = "0.1.0"
+__author__ = "J.C. Wolber"
+
+from sublimex.core import SublimeX
+from sublimex.transforms import TRANSFORMS, register_transform, get_transform, list_transforms
+from sublimex.objectives import (AGGREGATIONS, mean_objective, aggregate_objective, 
+                                 pattern_objective, create_custom_objective)
+from sublimex.models import LightGBMModel, SklearnModelWrapper
+from sublimex.visualization import (plot_feature_importance, plot_segment_on_signal,
+                                    plot_feature_distributions, plot_transform_comparison,
+                                    plot_optimization_history)
+
+__all__ = [
+    "__version__", "__author__", "SublimeX",
+    "TRANSFORMS", "register_transform", "get_transform", "list_transforms",
+    "AGGREGATIONS", "mean_objective", "aggregate_objective", "pattern_objective", "create_custom_objective",
+    "LightGBMModel", "SklearnModelWrapper",
+    "plot_feature_importance", "plot_segment_on_signal", "plot_feature_distributions", 
+    "plot_transform_comparison", "plot_optimization_history",
+]

sublimex/core.py

@@ -0,0 +1,221 @@
+"""SublimeX core module - interpretable feature extraction."""
+import numpy as np
+import json
+import os
+import warnings
+from typing import List, Dict, Any, Optional
+
+import optuna
+from sklearn.model_selection import KFold, StratifiedKFold, train_test_split
+
+from sublimex.transforms import TRANSFORMS
+from sublimex.objectives import default_objective
+from sublimex.models import LightGBMModel
+
+warnings.filterwarnings('ignore', category=optuna.exceptions.ExperimentalWarning)
+optuna.logging.set_verbosity(optuna.logging.WARNING)
+
+
+class MockTrial:
+    """Mock Optuna trial for replaying saved parameters."""
+    __slots__ = ('params',)
+    
+    def __init__(self, params):
+        self.params = params
+    
+    def suggest_int(self, name, low, high):
+        return int(self.params[name])
+    
+    def suggest_float(self, name, low, high):
+        return float(self.params[name])
+    
+    def suggest_categorical(self, name, choices):
+        return self.params[name]
+
+
+class SublimeX:
+    """SublimeX: Supervised Bottom-Up Localized Multi-Representative Feature Extraction."""
+    
+    def __init__(self, metric='auc', n_trials=300, inner_cv=1, val_size=0.5,
+                 verbose=False, show_progress_bar=False, transforms=None,
+                 objective_fn=None, model=None, sampler='tpe'):
+        self.metric = metric
+        self.n_trials = n_trials
+        self.inner_cv = inner_cv
+        self.val_size = val_size
+        self.verbose = verbose
+        self.show_progress_bar = show_progress_bar
+        self.transforms = transforms or TRANSFORMS
+        self.objective_fn = objective_fn or default_objective
+        self.model = model
+        self.sampler = sampler
+        
+        self.extracted_features: List[Dict[str, Any]] = []
+        self.transform_names: List[str] = list(self.transforms.keys())
+        self.n_channels: Optional[int] = None
+        self.n_time: Optional[int] = None
+        self._is_fitted: bool = False
+    
+    def _apply_transforms(self, data):
+        """Apply all transforms to input data."""
+        n_samples, n_channels, n_time = data.shape
+        out = np.empty((len(self.transform_names), n_samples, n_channels, n_time), dtype=np.float32)
+        for ti, tname in enumerate(self.transform_names):
+            flat = data.reshape(-1, n_time)
+            out[ti] = self.transforms[tname](flat).reshape(n_samples, n_channels, n_time)
+        return out
+    
+    def _extract_feature(self, params, ctx):
+        """Extract a single feature using saved parameters."""
+        ctx['extract_only'] = True
+        self.objective_fn(MockTrial(params), ctx)
+        ctx['extract_only'] = False
+        return ctx['last_feature']
+    
+    def _create_cv_splits(self, n_samples, y):
+        """Create CV splits for internal evaluation."""
+        if self.inner_cv == 1:
+            stratify = y if self.metric != 'rmse' else None
+            train_idx, val_idx = train_test_split(
+                np.arange(n_samples), test_size=self.val_size, 
+                random_state=42, stratify=stratify)
+            return [(train_idx, val_idx)]
+        cv_cls = StratifiedKFold if self.metric != 'rmse' else KFold
+        return list(cv_cls(self.inner_cv, shuffle=True, random_state=42).split(np.zeros(n_samples), y))
+    
+    def _create_sampler(self):
+        """Create Optuna sampler."""
+        if self.sampler == 'nsga2':
+            return optuna.samplers.NSGAIISampler()
+        return optuna.samplers.TPESampler(multivariate=True, group=True, constant_liar=True)
+    
+    def fit(self, input_series, y):
+        """Fit the feature extractor to training data."""
+        data = np.stack(list(input_series), axis=1).astype(np.float32)
+        n_samples, self.n_channels, self.n_time = data.shape
+        
+        if self.verbose:
+            print(f"\nSublimeX Feature Extraction")
+            print(f"  Samples: {n_samples}")
+            print(f"  Channels: {self.n_channels}")
+            print(f"  Time points: {self.n_time}")
+            print(f"  Transforms: {self.transform_names}")
+            print(f"  Metric: {self.metric}\n")
+        
+        if self.model is None:
+            task = 'regression' if self.metric == 'rmse' else 'classification'
+            self.model = LightGBMModel(task=task)
+        
+        cv_splits = self._create_cv_splits(n_samples, y)
+        transformed = self._apply_transforms(data)
+        
+        direction = 'minimize' if self.metric == 'rmse' else 'maximize'
+        is_maximize = direction == 'maximize'
+        
+        ctx = {
+            'transformed': transformed, 'y': y, 'model': self.model,
+            'metric': self.metric, 'n_channels': self.n_channels,
+            'n_time': self.n_time, 'transform_names': self.transform_names,
+            'cv_splits': cv_splits,
+        }
+        
+        self.extracted_features = []
+        current_X = np.empty((n_samples, 0), dtype=np.float32)
+        best_score = float('inf') if not is_maximize else -float('inf')
+        while True:
+            ctx['current_X'] = current_X
+            
+            study = optuna.create_study(direction=direction, sampler=self._create_sampler())
+            study.optimize(lambda t: self.objective_fn(t, ctx), n_trials=self.n_trials,
+                          show_progress_bar=self.show_progress_bar, n_jobs=-1)
+            
+            improved = (is_maximize and study.best_value > best_score) or \
+                       (not is_maximize and study.best_value < best_score)
+            
+            if not improved:
+                break
+            
+            best_score = study.best_value
+            params = study.best_params
+            self.extracted_features.append(params)
+            
+            feat = self._extract_feature(params, ctx)
+            current_X = np.hstack([current_X, feat]) if current_X.size else feat
+            
+            if self.verbose:
+                print(f"  Feature {len(self.extracted_features)}: {self.metric}={best_score:.5f}, params={params}")
+        
+        self._is_fitted = True
+        if self.verbose:
+            print(f"\nDiscovered {len(self.extracted_features)} features")
+        return self
+    
+    def transform(self, input_series):
+        """Transform data using extracted features."""
+        
+        data = np.stack(list(input_series), axis=1).astype(np.float32)
+        n_samples, n_channels, n_time = data.shape
+        transformed = self._apply_transforms(data)
+        
+        ctx = {'transformed': transformed, 'n_time': n_time, 
+               'n_channels': n_channels, 'transform_names': self.transform_names}
+        
+        features = [self._extract_feature(p, ctx) for p in self.extracted_features]
+        return np.hstack(features).astype(np.float32)
+    
+    def fit_transform(self, input_series, y):
+        """Fit and transform in one step."""
+        return self.fit(input_series, y).transform(input_series)
+    
+    def save_features(self, path):
+        """Save extracted feature parameters to JSON file."""
+        os.makedirs(os.path.dirname(path) or '.', exist_ok=True)
+        features_list = []
+        for i, params in enumerate(self.extracted_features):
+            feature_dict = {'feature_id': i + 1}
+            for k, v in params.items():
+                if isinstance(v, (np.integer, int)):
+                    feature_dict[k] = int(v)
+                elif isinstance(v, (np.floating, float)):
+                    feature_dict[k] = float(v)
+                else:
+                    feature_dict[k] = v
+            features_list.append(feature_dict)
+        with open(path, 'w') as f:
+            json.dump(features_list, f, indent=2)
+    
+    def load_features(self, path):
+        """Load feature parameters from JSON file."""
+        with open(path, 'r') as f:
+            features_list = json.load(f)
+        self.extracted_features = [{k: v for k, v in f.items() if k != 'feature_id'} 
+                                   for f in features_list]
+        self._is_fitted = True
+        return self
+    
+    def get_feature_descriptions(self):
+        """Get human-readable descriptions of extracted features."""
+        if not self.extracted_features:
+            return []
+        
+        descriptions = []
+        for i, params in enumerate(self.extracted_features):
+            t_idx = params.get('t', 0)
+            transform = self.transform_names[t_idx] if t_idx < len(self.transform_names) else f"transform_{t_idx}"
+            ch = params.get('ch', 0)
+            c, r = params.get('c', 0.5), params.get('r', 0.5)
+            
+            if self.n_time:
+                start = int(c * self.n_time - r * self.n_time / 2)
+                end = int(c * self.n_time + r * self.n_time / 2)
+                pos_str = f"positions {max(0, start)}-{min(self.n_time, end)}"
+            else:
+                pos_str = f"center={c:.2f}, range={r:.2f}"
+            
+            feat_type = params.get('feature_type', 'mean')
+            descriptions.append(f"Feature {i+1}: {feat_type} of {transform} in channel {ch}, {pos_str}")
+        return descriptions
+    
+    def __repr__(self):
+        status = "fitted" if self._is_fitted else "not fitted"
+        return f"SublimeX(metric='{self.metric}', n_trials={self.n_trials}, status={status}, n_features={len(self.extracted_features)})"

sublimex/models.py

@@ -0,0 +1,102 @@
+"""ML model wrappers for SublimeX."""
+import numpy as np
+from sklearn.metrics import roc_auc_score, accuracy_score, mean_squared_error
+
+
+def _compute_score(y_true, pred, metric):
+    """Compute evaluation metric."""
+    if metric == 'auc':
+        if pred.ndim == 2 and pred.shape[1] == 2:
+            return roc_auc_score(y_true, pred[:, 1])
+        elif pred.ndim == 2:
+            return roc_auc_score(y_true, pred, multi_class='ovr')
+        return roc_auc_score(y_true, pred)
+    elif metric == 'accuracy':
+        if pred.ndim == 2:
+            pred = pred.argmax(axis=1)
+        return accuracy_score(y_true, pred)
+    elif metric == 'rmse':
+        return np.sqrt(mean_squared_error(y_true, pred))
+    raise ValueError(f"Unknown metric: {metric}")
+
+
+class LightGBMModel:
+    """LightGBM wrapper for SublimeX evaluation loop."""
+    
+    _BASE_PARAMS = {
+        'max_depth': 3, 
+        'data_sample_strategy': 'goss',
+        'verbosity': -1,
+        'force_row_wise': True,
+    }
+    
+    def __init__(self, task='classification', max_depth=3, n_estimators=100, early_stopping_rounds=10):
+        self.task = task
+        self.max_depth = max_depth
+        self.n_estimators = n_estimators
+        self.early_stopping_rounds = early_stopping_rounds
+        self.model = None
+        
+        from lightgbm import LGBMClassifier, LGBMRegressor, early_stopping
+        self._clf_cls = LGBMClassifier
+        self._reg_cls = LGBMRegressor
+        self._early_stopping = early_stopping
+        self._model_cls = self._clf_cls if task == 'classification' else self._reg_cls
+    
+    def evaluate(self, X_train, y_train, X_val, y_val, metric):
+        """Train and evaluate on validation set."""
+        params = {**self._BASE_PARAMS, 'num_threads': 1}
+        model = self._model_cls(**params)
+        model.fit(X_train, y_train, eval_set=[(X_val, y_val)],
+                  callbacks=[self._early_stopping(self.early_stopping_rounds, verbose=False)])
+        pred = model.predict_proba(X_val) if metric == 'auc' and self.task == 'classification' else model.predict(X_val)
+        return _compute_score(y_val, pred, metric)
+    
+    def test(self, X_train, y_train, X_test, y_test, metric):
+        """Train on full training set and evaluate on test set."""
+        params = {**self._BASE_PARAMS, 'num_threads': -1}
+        self.model = self._model_cls(**params)
+        self.model.fit(X_train, y_train)
+        pred = self.model.predict_proba(X_test) if metric == 'auc' and self.task == 'classification' else self.model.predict(X_test)
+        return _compute_score(y_test, pred, metric)
+    
+    def predict(self, X):
+        return self.model.predict(X)
+    
+    def predict_proba(self, X):
+        return self.model.predict_proba(X)
+
+
+class SklearnModelWrapper:
+    """Wrapper for any sklearn estimator."""
+    
+    def __init__(self, estimator, clone_for_each_eval=True):
+        self.estimator = estimator
+        self.clone_for_each_eval = clone_for_each_eval
+        self.model = None
+        self._is_classifier = hasattr(estimator, 'predict_proba')
+        from sklearn.base import clone
+        self._clone = clone
+    
+    def _get_estimator(self):
+        return self._clone(self.estimator) if self.clone_for_each_eval else self.estimator
+    
+    def evaluate(self, X_train, y_train, X_val, y_val, metric):
+        """Train and evaluate on validation set."""
+        model = self._get_estimator()
+        model.fit(X_train, y_train)
+        pred = model.predict_proba(X_val) if metric == 'auc' and self._is_classifier else model.predict(X_val)
+        return _compute_score(y_val, pred, metric)
+    
+    def test(self, X_train, y_train, X_test, y_test, metric):
+        """Train on full training set and evaluate on test set."""
+        self.model = self._get_estimator()
+        self.model.fit(X_train, y_train)
+        pred = self.model.predict_proba(X_test) if metric == 'auc' and self._is_classifier else self.model.predict(X_test)
+        return _compute_score(y_test, pred, metric)
+    
+    def predict(self, X):
+        return self.model.predict(X)
+    
+    def predict_proba(self, X):
+        return self.model.predict_proba(X)

sublimex/objectives.py

@@ -0,0 +1,152 @@
+"""Objective functions for SublimeX optimization."""
+import numpy as np
+from numpy.lib.stride_tricks import sliding_window_view
+from typing import Callable, Dict, Any
+
+
+AGGREGATIONS = {
+    'mean': lambda x: x.mean(axis=1, keepdims=True),
+    'min': lambda x: x.min(axis=1, keepdims=True),
+    'max': lambda x: x.max(axis=1, keepdims=True),
+    'range': lambda x: np.ptp(x, axis=1, keepdims=True),
+    'std': lambda x: x.std(axis=1, keepdims=True),
+    'median': lambda x: np.median(x, axis=1, keepdims=True),
+    'argmin': lambda x: x.argmin(axis=1, keepdims=True).astype(np.float32) / max(x.shape[1] - 1, 1),
+    'argmax': lambda x: x.argmax(axis=1, keepdims=True).astype(np.float32) / max(x.shape[1] - 1, 1),
+}
+AGG_KEYS = list(AGGREGATIONS.keys())
+
+
+def get_segment_indices(center: float, range_val: float, n_time: int) -> tuple:
+    """Convert normalized center and range to segment indices."""
+    center_idx = center * (n_time - 1)
+    half_width = (range_val * (n_time - 1)) * 0.5
+    start = max(0, int(center_idx - half_width))
+    end = min(n_time - 1, int(center_idx + half_width))
+    return start, end
+
+
+def _evaluate(feature: np.ndarray, ctx: Dict[str, Any]) -> float:
+    """Evaluate a candidate feature using cross-validation."""
+    ctx['last_feature'] = feature
+    if ctx.get('extract_only'):
+        return 0.0
+    
+    current_X = ctx['current_X']
+    X = np.hstack([current_X, feature]) if current_X.size else feature
+    
+    scores = []
+    for train_idx, val_idx in ctx['cv_splits']:
+        score = ctx['model'].evaluate(X[train_idx], ctx['y'][train_idx], 
+                                      X[val_idx], ctx['y'][val_idx], ctx['metric'])
+        scores.append(score)
+    return np.mean(scores)
+
+
+def _get_segment(trial, ctx: Dict[str, Any], feature_type: str) -> tuple:
+    """Extract segment parameters from trial and retrieve data."""
+    ch = trial.suggest_int('ch', 0, ctx['n_channels'] - 1)
+    t = trial.suggest_int('t', 0, len(ctx['transform_names']) - 1)
+    c = trial.suggest_float('c', 0, 1)
+    r = trial.suggest_float('r', 0, 1)
+    
+    start, end = get_segment_indices(c, r, ctx['n_time'])
+    segment = ctx['transformed'][t, :, ch, start:end+1]
+    
+    params = {
+        'feature_type': feature_type, 'channel': ch, 'transform_idx': t,
+        'transform_name': ctx['transform_names'][t], 'center': c, 'range': r,
+        'start_idx': start, 'end_idx': end,
+    }
+    return segment, params
+
+
+def mean_objective(trial, ctx: Dict[str, Any]) -> float:
+    """Mean objective - extract mean value over optimized segment."""
+    segment, _ = _get_segment(trial, ctx, 'mean')
+    feature = segment.mean(axis=1, keepdims=True).astype(np.float32)
+    return _evaluate(feature, ctx)
+
+
+def aggregate_objective(trial, ctx: Dict[str, Any]) -> float:
+    """Aggregate objective - choose from multiple aggregation functions."""
+    segment, _ = _get_segment(trial, ctx, 'aggregate')
+    agg_name = trial.suggest_categorical('agg', AGG_KEYS)
+    feature = AGGREGATIONS[agg_name](segment).astype(np.float32)
+    return _evaluate(feature, ctx)
+
+
+def pattern_objective(trial, ctx: Dict[str, Any]) -> float:
+    """Pattern objective - quadratic B-spline matching."""
+    segment, params = _get_segment(trial, ctx, 'pattern')
+    
+    w = trial.suggest_float('w', 0.05, 0.5)
+    cp0 = trial.suggest_float('cp0', 0, 1)
+    cp1 = trial.suggest_float('cp1', 0, 1)
+    cp2 = trial.suggest_float('cp2', 0, 1)
+    
+    n_time = ctx['n_time']
+    n_samples, segment_len = segment.shape
+    width = min(max(2, int(w * n_time)), segment_len)
+    
+    if width > segment_len or segment_len - width + 1 <= 0:
+        return _evaluate(np.full((n_samples, 1), np.inf, dtype=np.float32), ctx)
+    
+    t = np.linspace(0, 1, width, dtype=np.float32)
+    pattern = (1 - t) ** 2 * cp0 + 2 * (1 - t) * t * cp1 + t ** 2 * cp2
+    
+    windows = sliding_window_view(segment, window_shape=width, axis=1)
+    distances = np.linalg.norm(windows - pattern, axis=2) / np.sqrt(width)
+    feature = distances.min(axis=1, keepdims=True).astype(np.float32)
+    
+    return _evaluate(feature, ctx)
+
+
+default_objective = mean_objective
+
+
+def create_custom_objective(aggregation_fn: Callable, name: str = 'custom') -> Callable:
+    """Create a custom objective with user-defined aggregation."""
+    def custom_objective(trial, ctx: Dict[str, Any]) -> float:
+        segment, _ = _get_segment(trial, ctx, name)
+        feature = aggregation_fn(segment).astype(np.float32)
+        return _evaluate(feature, ctx)
+    custom_objective.__name__ = f'{name}_objective'
+    return custom_objective
+
+
+def parallel_objective(trial, ctx):
+    """Parallel objective: optimize multiple features simultaneously.
+    
+    Suggests parameters for N features at once (ch_0, t_0, c_0, r_0, ..., ch_N-1, ...)
+    and evaluates the combined feature set.
+    """
+    n_features = ctx.get('n_target_features', 10)  # Default fallback
+    
+    # Extract all features in parallel with different parameters for each
+    features = []
+    for i in range(n_features):
+        # Suggest different parameters for each feature
+        ch = trial.suggest_int(f'ch_{i}', 0, ctx['n_channels'] - 1)
+        t_idx = trial.suggest_int(f't_{i}', 0, len(ctx['transform_names']) - 1)
+        c = trial.suggest_float(f'c_{i}', 0, 1)
+        r = trial.suggest_float(f'r_{i}', 0, 1)
+        s, e = get_segment_indices(c, r, ctx['n_time'])
+        segment = ctx['transformed'][t_idx, :, ch, s:e+1]
+        feat = segment.mean(axis=1, keepdims=True).astype(np.float32)
+        features.append(feat)
+    
+    # Combine all features
+    combined_feat = np.hstack(features) if len(features) > 1 else features[0]
+    
+    # Store for extraction mode
+    ctx['last_feature'] = combined_feat
+    if ctx.get('extract_only'):
+        return 0.0
+    
+    # Evaluate combined feature set
+    current_X = ctx['current_X']
+    X = np.hstack([current_X, combined_feat]) if current_X.size else combined_feat
+    model, y, metric, cv_splits = ctx['model'], ctx['y'], ctx['metric'], ctx['cv_splits']
+    total = sum(model.evaluate(X[tr], y[tr], X[va], y[va], metric) for tr, va in cv_splits)
+    return total / len(cv_splits)

sublimex/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561
+# This file indicates that the sublime package supports type hints

sublimex/transforms.py

@@ -0,0 +1,38 @@
+"""Signal transforms for SublimeX feature extraction."""
+import numpy as np
+from typing import Callable, Dict, List
+
+
+def _fft_power(d):
+    """FFT power spectrum interpolated to original length."""
+    p = np.abs(np.fft.rfft(d, axis=-1)) ** 2
+    x = np.linspace(0, p.shape[-1]-1, d.shape[-1])
+    idx = np.minimum(x.astype(int), p.shape[-1]-2)
+    return p[..., idx] * (1 - (x - idx)) + p[..., idx + 1] * (x - idx)
+
+
+TRANSFORMS: Dict[str, Callable] = {
+    'raw': lambda d: d,
+    'zscore': lambda d: (d - d.mean(-1, keepdims=True)) / (d.std(-1, keepdims=True) + 1e-8),
+    'derivative': lambda d: np.gradient(d, axis=-1),
+    'fft_power': _fft_power,
+}
+
+
+def register_transform(name: str, func: Callable, overwrite: bool = False):
+    """Register a custom transform function."""
+    if name in TRANSFORMS and not overwrite:
+        raise ValueError(f"Transform '{name}' already exists. Use overwrite=True.")
+    TRANSFORMS[name] = func
+
+
+def get_transform(name: str) -> Callable:
+    """Get transform by name."""
+    if name not in TRANSFORMS:
+        raise KeyError(f"Transform '{name}' not found. Available: {list(TRANSFORMS.keys())}")
+    return TRANSFORMS[name]
+
+
+def list_transforms() -> List[str]:
+    """List available transform names."""
+    return list(TRANSFORMS.keys())

sublimex/visualization.py

@@ -0,0 +1,131 @@
+"""Visualization utilities for SublimeX."""
+import numpy as np
+from typing import List, Dict, Any, Optional, Tuple, Union
+
+
+def _import_plt():
+    import matplotlib.pyplot as plt
+    return plt
+
+
+def plot_feature_importance(importances, descriptions=None, top_k=None, 
+                            figsize=(10, 6), color='#2ecc71'):
+    """Plot feature importance as horizontal bar chart."""
+    plt = _import_plt()
+    n = len(importances)
+    if descriptions is None:
+        descriptions = [f'Feature {i+1}' for i in range(n)]
+    
+    indices = np.argsort(importances)[::-1]
+    if top_k:
+        indices = indices[:top_k]
+    
+    fig, ax = plt.subplots(figsize=figsize)
+    y_pos = np.arange(len(indices))
+    ax.barh(y_pos, importances[indices], color=color)
+    ax.set_yticks(y_pos)
+    ax.set_yticklabels([descriptions[i] for i in indices])
+    ax.invert_yaxis()
+    ax.set_xlabel('Importance')
+    plt.tight_layout()
+    return fig
+
+
+def plot_segment_on_signal(signal, feature_params, n_time, transform_names=None,
+                           sample_idx=0, figsize=(12, 4)):
+    """Visualize where a feature's segment falls on the signal."""
+    plt = _import_plt()
+    sig = signal if signal.ndim == 1 else signal[sample_idx]
+    
+    c, r, t = feature_params.get('c', 0.5), feature_params.get('r', 0.5), feature_params.get('t', 0)
+    center_idx = c * (n_time - 1)
+    half_width = (r * (n_time - 1)) * 0.5
+    start, end = max(0, int(center_idx - half_width)), min(n_time - 1, int(center_idx + half_width))
+    
+    transform_name = transform_names[t] if transform_names and t < len(transform_names) else f'transform_{t}'
+    
+    fig, ax = plt.subplots(figsize=figsize)
+    ax.plot(sig, color='#3498db', linewidth=1.5, label='Signal')
+    ax.axvspan(start, end, alpha=0.3, color='#e74c3c', label=f'Segment [{start}:{end}]')
+    ax.axvline(start, color='#e74c3c', linestyle='--', alpha=0.7)
+    ax.axvline(end, color='#e74c3c', linestyle='--', alpha=0.7)
+    ax.set_xlabel('Time')
+    ax.set_ylabel('Value')
+    ax.set_title(f'Feature segment (transform: {transform_name})')
+    ax.legend()
+    plt.tight_layout()
+    return fig
+
+
+def plot_feature_distributions(features, y, feature_idx=0, feature_description=None,
+                               figsize=(10, 5), bins=30):
+    """Plot distribution of a feature's values across classes."""
+    plt = _import_plt()
+    feat_values = features[:, feature_idx]
+    classes = np.unique(y)
+    colors = plt.cm.get_cmap('tab10')(range(len(classes)))
+    
+    fig, axes = plt.subplots(1, 2, figsize=figsize)
+    
+    for i, cls in enumerate(classes):
+        mask = y == cls
+        axes[0].hist(feat_values[mask], bins=bins, alpha=0.6, color=colors[i], label=f'Class {cls}')
+    axes[0].set_xlabel('Feature Value')
+    axes[0].set_ylabel('Count')
+    axes[0].legend()
+    
+    bp = axes[1].boxplot([feat_values[y == c] for c in classes], 
+                         labels=[f'Class {c}' for c in classes], patch_artist=True)
+    for patch, color in zip(bp['boxes'], colors):
+        patch.set_facecolor(color)
+        patch.set_alpha(0.6)
+    axes[1].set_ylabel('Feature Value')
+    
+    fig.suptitle(feature_description or f'Feature {feature_idx + 1}', fontweight='bold')
+    plt.tight_layout()
+    return fig
+
+
+def plot_transform_comparison(signal, transforms, figsize=(12, 8), sample_idx=0):
+    """Show a signal under all available transforms."""
+    plt = _import_plt()
+    sig = signal.reshape(1, -1) if signal.ndim == 1 else signal[sample_idx:sample_idx+1]
+    
+    n_transforms = len(transforms)
+    n_cols, n_rows = 2, (n_transforms + 1) // 2
+    fig, axes = plt.subplots(n_rows, n_cols, figsize=figsize)
+    axes = axes.flatten()
+    colors = plt.cm.viridis(np.linspace(0, 0.8, n_transforms))
+    
+    for i, (name, fn) in enumerate(transforms.items()):
+        try:
+            axes[i].plot(fn(sig)[0], color=colors[i], linewidth=1.5)
+            axes[i].set_title(name, fontweight='bold')
+        except Exception as e:
+            axes[i].text(0.5, 0.5, f'Error: {str(e)[:30]}', ha='center', va='center', transform=axes[i].transAxes)
+        axes[i].set_xlabel('Time')
+        axes[i].set_ylabel('Value')
+    
+    for i in range(n_transforms, len(axes)):
+        axes[i].set_visible(False)
+    
+    fig.suptitle('Signal Transforms Comparison', fontsize=14, fontweight='bold')
+    plt.tight_layout()
+    return fig
+
+
+def plot_optimization_history(study_or_scores, figsize=(10, 5), color='#9b59b6'):
+    """Plot optimization progress over trials."""
+    plt = _import_plt()
+    scores = [t.value for t in study_or_scores.trials if t.value is not None] if hasattr(study_or_scores, 'trials') else list(study_or_scores)
+    
+    fig, ax = plt.subplots(figsize=figsize)
+    trials = np.arange(1, len(scores) + 1)
+    ax.plot(trials, scores, alpha=0.3, color=color, label='Trial scores')
+    ax.plot(trials, np.maximum.accumulate(scores), color=color, linewidth=2, label='Best so far')
+    ax.set_xlabel('Trial')
+    ax.set_ylabel('Score')
+    ax.set_title('Optimization Progress')
+    ax.legend()
+    plt.tight_layout()
+    return fig

sublimex-0.1.0.dist-info/METADATA

@@ -0,0 +1,360 @@
+Metadata-Version: 2.4
+Name: sublimex
+Version: 0.1.0
+Summary: SublimeX: Supervised Bottom-Up Localized Multi-Representative Feature eXtraction for time series and spatial data
+Author-email: "J.C. Wolber" <jwolber@ukaachen.de>
+Maintainer-email: "J.C. Wolber" <jwolber@ukaachen.de>
+License: MIT
+Project-URL: Homepage, https://github.com/Prgrmmrjns/SublimeX
+Project-URL: Documentation, https://github.com/Prgrmmrjns/SublimeX#readme
+Project-URL: Repository, https://github.com/Prgrmmrjns/SublimeX.git
+Project-URL: Issues, https://github.com/Prgrmmrjns/SublimeX/issues
+Keywords: time series,feature extraction,machine learning,interpretable ml,signal processing,classification,regression,bayesian optimization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: optuna>=3.0.0
+Requires-Dist: lightgbm>=3.3.0
+Provides-Extra: visualization
+Requires-Dist: matplotlib>=3.5.0; extra == "visualization"
+Provides-Extra: full
+Requires-Dist: matplotlib>=3.5.0; extra == "full"
+Requires-Dist: pandas>=1.3.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=0.950; extra == "dev"
+Requires-Dist: matplotlib>=3.5.0; extra == "dev"
+Requires-Dist: pandas>=1.3.0; extra == "dev"
+Dynamic: license-file
+
+# SublimeX
+
+**Supervised Bottom-Up Localized Multi-Representative Feature eXtraction**
+
+[![PyPI version](https://badge.fury.io/py/sublimex.svg)](https://badge.fury.io/py/sublimex)
+[![Python 3.11+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+SublimeX is an interpretable feature extraction framework for time series and spatial data. It discovers a minimal set of task-specific features through Bayesian optimization, where each feature has explicit, human-readable semantics.
+
+## Key Features
+
+- **Minimal feature sets**: Typically 5-15 features vs. thousands from other methods
+- **Full interpretability**: Each feature = statistic over optimized segment of transformed signal
+- **Competitive performance**: Matches deep learning on many tasks
+- **Modular design**: Custom transforms, objectives, and ML models
+
+## Installation
+
+```bash
+pip install sublimex
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/Prgrmmrjns/SublimeX.git
+cd SublimeX
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import sublimex
+import numpy as np
+from sklearn.model_selection import train_test_split
+from sklearn.ensemble import RandomForestClassifier
+
+# Your data: list of arrays/DataFrames, one per channel
+# Each array has shape (n_samples, n_time_points)
+X = [channel1_data, channel2_data, channel3_data]  # 3 channels
+y = labels  # Binary or continuous targets
+
+# Split data
+X_train, X_test, y_train, y_test = train_test_split(
+    range(len(y)), test_size=0.2, stratify=y, random_state=42
+)
+X_train = [x.iloc[X_train] for x in X]
+X_test = [x.iloc[X_test] for x in X]
+y_train, y_test = y[X_train], y[X_test]
+
+# Fit SublimeX
+model = sublimex.SublimeX(metric='auc', n_trials=100, verbose=True)
+train_features = model.fit_transform(X_train, y_train)
+test_features = model.transform(X_test)
+
+# Use with any classifier
+clf = RandomForestClassifier()
+clf.fit(train_features, y_train)
+predictions = clf.predict(test_features)
+
+# Interpret discovered features
+for desc in model.get_feature_descriptions():
+    print(desc)
+```
+
+## How It Works
+
+SublimeX discovers discriminative features through a simple but effective process:
+
+1. **Signal Transformation**: Apply multiple transforms to create different "views" of the data (raw, z-score normalized, derivative, FFT power spectrum)
+
+2. **Segment Optimization**: Use Bayesian optimization (Optuna) to find segments that maximize downstream model performance
+
+3. **Feature Extraction**: Compute statistics (e.g., mean) over discovered segments
+
+4. **Iterative Discovery**: Repeat until adding new features no longer improves performance
+
+Each discovered feature is fully interpretable:
+> "Mean of z-score normalized signal in channel 2, positions 40-60"
+
+## Configuration
+
+### Basic Parameters
+
+```python
+import sublimex
+
+model = sublimex.SublimeX(
+    metric='auc',          # 'auc', 'accuracy', or 'rmse'
+    n_trials=300,          # Optimization trials per feature
+    inner_cv=1,            # Internal CV folds (1 = single split)
+    val_size=0.5,          # Validation size when inner_cv=1
+    verbose=True,          # Print progress
+)
+```
+
+### Custom Transforms
+
+```python
+import sublimex
+
+# Register a custom transform
+def hilbert_envelope(data):
+    from scipy.signal import hilbert
+    return np.abs(hilbert(data, axis=-1))
+
+sublimex.register_transform('hilbert', hilbert_envelope)
+
+# Use specific transforms
+model = sublimex.SublimeX(
+    transforms={
+        'raw': lambda x: x,
+        'hilbert': hilbert_envelope,
+    }
+)
+```
+
+### Custom Objective Functions
+
+```python
+import sublimex
+import numpy as np
+
+# Create objective with custom aggregation
+def rms(segment):
+    """Root mean square."""
+    return np.sqrt((segment ** 2).mean(axis=1, keepdims=True))
+
+rms_objective = sublimex.create_custom_objective(rms, 'rms')
+model = sublimex.SublimeX(objective_fn=rms_objective)
+```
+
+### Custom ML Models
+
+```python
+import sublimex
+from sklearn.ensemble import RandomForestClassifier
+
+# Wrap any sklearn estimator
+rf = RandomForestClassifier(n_estimators=100)
+model = sublimex.SublimeX(model=sublimex.SklearnModelWrapper(rf))
+```
+
+## Built-in Options
+
+### Transforms
+
+| Transform | Description | Use Case |
+|-----------|-------------|----------|
+| `raw` | Identity (original signal) | Amplitude differences |
+| `zscore` | Z-score normalization | Shape differences |
+| `derivative` | First-order gradient | Rate of change, transitions |
+| `fft_power` | FFT power spectrum | Frequency content, periodicity |
+
+### Aggregations (for `aggregate_objective`)
+
+| Aggregation | Description |
+|-------------|-------------|
+| `mean` | Average value (default) |
+| `min`, `max` | Extreme values |
+| `range` | max - min |
+| `std` | Standard deviation |
+| `median` | Robust central tendency |
+| `argmin`, `argmax` | Position of extrema |
+
+### Objectives
+
+| Objective | Description |
+|-----------|-------------|
+| `mean_objective` | Mean over segment (default, most interpretable) |
+| `aggregate_objective` | Choose from 8 aggregations |
+| `pattern_objective` | B-spline pattern matching |
+
+## Visualization
+
+```python
+import sublimex
+import matplotlib.pyplot as plt
+
+# Compare feature values across classes
+fig = sublimex.plot_feature_distributions(features, y, feature_idx=0)
+plt.show()
+
+# Show where a feature's segment falls on the signal
+fig = sublimex.plot_segment_on_signal(
+    signal, model.extracted_features[0], model.n_time
+)
+plt.show()
+
+# Compare all transforms for a sample
+fig = sublimex.plot_transform_comparison(signal, sublimex.TRANSFORMS)
+plt.show()
+```
+
+## Saving and Loading
+
+```python
+import sublimex
+
+# Save discovered features
+model.save_features('features.json')
+
+# Load and reuse
+new_model = sublimex.SublimeX()
+new_model.load_features('features.json')
+features = new_model.transform(X_new)
+```
+
+## Complete Example: Synthetic Multi-Channel Time Series
+
+```python
+"""Complete example with synthetic data."""
+import sublimex
+import numpy as np
+import pandas as pd
+from sklearn.model_selection import train_test_split
+from sklearn.metrics import roc_auc_score
+import lightgbm as lgb
+
+# Generate synthetic multi-channel time series
+np.random.seed(42)
+n_samples, n_channels, n_bins = 500, 5, 200
+
+X = []
+y = np.random.randint(0, 2, n_samples)
+
+for channel in range(n_channels):
+    channel_data = []
+    for i in range(n_samples):
+        t = np.linspace(0, 4 * np.pi, n_bins)
+        if y[i] == 1:
+            # Class 1: Higher amplitude with distinctive peak
+            signal = 2.0 * np.sin(t) + 1.5 * np.sin(2 * t)
+            peak = n_bins // 2
+            signal[peak-20:peak+20] += 1.5 * np.exp(-((np.arange(40) - 20) ** 2) / 50)
+        else:
+            # Class 0: Lower amplitude, more noise
+            signal = 1.0 * np.sin(t) + 0.5 * np.sin(3 * t)
+        signal += np.random.normal(0, 0.3, n_bins)
+        channel_data.append(signal)
+    
+    X.append(pd.DataFrame(channel_data, columns=[f'bin_{j}' for j in range(n_bins)]))
+
+# Split data
+idx_train, idx_test = train_test_split(
+    range(len(y)), test_size=0.2, stratify=y, random_state=42
+)
+X_train = [x.iloc[idx_train].astype(np.float32) for x in X]
+X_test = [x.iloc[idx_test].astype(np.float32) for x in X]
+y_train, y_test = y[idx_train], y[idx_test]
+
+# Discover features with SublimeX
+model = sublimex.SublimeX(metric='auc', n_trials=50, verbose=True)
+train_features = model.fit_transform(X_train, y_train)
+test_features = model.transform(X_test)
+
+print(f"Discovered {train_features.shape[1]} features")
+
+# Train classifier
+clf = lgb.LGBMClassifier(n_estimators=100, verbose=-1)
+clf.fit(train_features, y_train)
+auc = roc_auc_score(y_test, clf.predict_proba(test_features)[:, 1])
+print(f"Test AUC: {auc:.4f}")
+
+# Interpret features
+print("\nDiscovered Features:")
+for desc in model.get_feature_descriptions():
+    print(f"  {desc}")
+
+# Visualize
+import matplotlib.pyplot as plt
+
+fig = sublimex.plot_feature_importance(
+    clf.feature_importances_, 
+    model.get_feature_descriptions()
+)
+plt.show()
+```
+
+## Comparison with Other Methods
+
+| Method | Features | Interpretability | Optimization |
+|--------|----------|------------------|--------------|
+| **SublimeX** | 5-15 | High (explicit segments) | Bayesian |
+| tsfresh | 100-800 | Medium (statistical) | Filter |
+| catch22 | 22 | Medium (fixed set) | None |
+| MiniRocket | ~10,000 | Low | Deterministic |
+| RDST | 2k-10k | Medium (shapelets) | Random |
+
+## Citation
+
+If you use SublimeX in your research, please cite:
+
+```bibtex
+@software{sublimex2025,
+  title={SublimeX: Supervised Bottom-Up Localized Multi-Representative Feature eXtraction},
+  author={Wolber, J.C.},
+  year={2026},
+  url={https://github.com/Prgrmmrjns/SublimeX}
+}
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

sublimex-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+sublimex/__init__.py,sha256=_IwnQG13qAVNG3K54Z10iZ7IIoOhBsQsDKVmyOxJMXI,1172
+sublimex/core.py,sha256=6AVhcEEhEpfZeRhgF8--4im0BSG_4lCICFilwUlijzs,9262
+sublimex/models.py,sha256=nA8SUBDqM5ChXBYiND8RgGvR_eCitE3Tjch2Xh0Osmc,4155
+sublimex/objectives.py,sha256=eqJJUTA57dIcXP22DeZNozapzb0xO7iiY8SOKoQx_mo,6159
+sublimex/py.typed,sha256=IVB0agohk5jYgq7eRKHocR6LrSNCBZrlPuv5x-_BiLM,93
+sublimex/transforms.py,sha256=tDH2xluUtC-LAlP1-KEZ3cO7eMGM2BTuRh_LtTpcS0Q,1284
+sublimex/visualization.py,sha256=JKv7ij2agowG8e3nHuu6dKeRiMJ9_bG5oi8X4AxEQ2s,5094
+sublimex-0.1.0.dist-info/licenses/LICENSE,sha256=rikCGiAwdvAZnZTcZD0QCqKOawQkigjw4yfcf0aiS5U,1068
+sublimex-0.1.0.dist-info/METADATA,sha256=w0MncQMgLzknKgR1LngO5IITzvUpBN9DP45byGrp0OI,11164
+sublimex-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+sublimex-0.1.0.dist-info/top_level.txt,sha256=paeo1dixjEC0yxT-C9QwOODcZlG9uFF7nWBEHh18NKU,9
+sublimex-0.1.0.dist-info/RECORD,,

sublimex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sublimex-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 J.C. Wolber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sublimex-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sublimex