Source code for protspect.sklearn

"""Optional scikit-learn integration; install Protspect with the ``ml`` extra."""

from copy import deepcopy
from collections import Counter
from collections.abc import Mapping

import numpy as np

try:
    from sklearn.base import BaseEstimator, TransformerMixin
    from sklearn.utils.validation import check_is_fitted
except ImportError as error:
    raise ImportError("Protspect sklearn integration requires scikit-learn; install Protspect[ml]") from error

from . import __version__
from .embeddings import b100
from ._sequence import _length, _sequences
from .transforms import transform_sequence, transform_pair, _selection, _export_features
from .preprocessing import validate_preprocessing
from .utility import frequency_select_physical


def _copy_embedding(embedding):
    """Validate and snapshot every channel, including symbols unseen in training."""
    if not isinstance(embedding, Mapping) or not embedding:
        raise ValueError("embedding must be a nonempty mapping of channels")
    result = {}
    alphabet = None
    for name, values in embedding.items():
        if not isinstance(name, str) or not name or not isinstance(values, Mapping) or not values:
            raise ValueError("embedding channels require nonempty names and residue mappings")
        if any(not isinstance(aa, str) or len(aa) != 1 for aa in values):
            raise ValueError("embedding symbols must be single-character strings")
        if alphabet is not None and set(values) != alphabet:
            raise ValueError("all embedding channels must cover the same alphabet")
        alphabet = set(values)
        if any(np.ndim(value) != 0 or np.iscomplexobj(value) for value in values.values()):
            raise ValueError("embedding values must be finite real scalars")
        try:
            channel = {aa: float(value) for aa, value in values.items()}
        except (TypeError, ValueError, OverflowError) as error:
            raise ValueError("embedding values must be finite real scalars") from error
        if not np.isfinite(list(channel.values())).all():
            raise ValueError("embedding values must be finite real scalars")
        result[name] = channel
    return result


def _channel_statistics(sequences, embedding, standardize):
    """Compute residue-weighted population moments using only training residues."""
    counts = Counter(aa for sequence in sequences for aa in sequence)
    unknown = set(counts) - set(next(iter(embedding.values())))
    if unknown:
        raise ValueError(f"training sequences contain unknown residues: {sorted(unknown)}")
    residues = list(counts)
    weights = np.array([counts[aa] for aa in residues], dtype=float)
    weights /= weights.sum()
    means, scales, effective = {}, {}, {}
    for name, channel in embedding.items():
        values = np.array([channel[aa] for aa in residues])
        mean, scale = 0.0, 1.0
        if standardize:
            peak = np.max(np.abs(values))
            unit = values / peak if peak else np.zeros_like(values)
            unit_mean = float(weights @ unit)
            mean = float(values[0]) if np.all(values == values[0]) else float(peak * unit_mean)
            deviations = unit - (mean / peak if peak else 0.0)
            scale = float(peak * np.sqrt(weights @ deviations**2))
        if not np.isfinite([mean, scale]).all():
            raise ValueError("channel statistics overflowed; rescale the embedding")
        means[name], scales[name] = mean, scale if scale > 0 else 1.0
        effective[name] = {aa: (value - mean) / scales[name] for aa, value in channel.items()}
        if not np.isfinite(list(effective[name].values())).all():
            raise ValueError("channel standardization produced nonfinite values")
    return means, scales, effective


def _samples(X, paired):
    """Materialize single sequences or exact two-chain samples without truncation."""
    if not paired:
        return _sequences(X)
    if isinstance(X, str):
        raise TypeError('provide an iterable of two-sequence pairs')
    samples = []
    for pair in X:
        if isinstance(pair, str):
            raise ValueError('each paired sample must contain exactly two sequences')
        pair = list(pair)
        if len(pair) != 2:
            raise ValueError('each paired sample must contain exactly two sequences')
        samples.append(tuple(_sequences(pair)))
    if not samples:
        raise ValueError('provide at least one two-sequence pair')
    return samples


def _jsonable(value):
    """Copy numerical provenance into JSON-safe values, including Z-plane axes."""
    if isinstance(value, np.ndarray):
        if np.iscomplexobj(value):
            return {'real': value.real.tolist(), 'imaginary': value.imag.tolist()}
        return value.tolist()
    if isinstance(value, np.generic):
        return _jsonable(value.item())
    if isinstance(value, complex):
        return {'real': value.real, 'imaginary': value.imag}
    if isinstance(value, dict):
        return {k: _jsonable(v) for k,v in value.items()}
    if isinstance(value, (list, tuple)):
        return [_jsonable(v) for v in value]
    return deepcopy(value)


[docs] class SequenceTransformer(TransformerMixin, BaseEstimator): """Fit one coefficient-feature schema for every transform and single/paired inputs. method selects fourier, z, mellin, or wavelet. embedding defaults to BLOSUM100. length defaults to the next power of two covering training chains only. Longer held-out chains raise. normalization and center operate on each real chain before padding. standardize_channels learns training-residue moments. component is amplitude, phase, real, imaginary, or an ordered tuple thereof. kinds selects coefficients and/or cross_coefficients. selector receives a dictionary of coordinate arrays and returns a same-shape boolean mask; an explicit boolean mask is also accepted. It is evaluated only at fit, copied, and frozen. Transform-specific options (radius, mellin_c, wavelet, level, mode) go in transform_options. With paired=True, X contains (A, B) samples and features describe all ordered A/B channel products. Non-Fourier products remain coefficient products rather than frequency-domain cross-spectra. Use inside a Pipeline so grid and channel moments fit within each CV fold. get_feature_metadata returns independent JSON-safe provenance. set_output supports pandas. Constructor mutations apply only after refitting; set_params invalidates fit. The SpectralTransformer compatibility subclass delegates here while preserving the original Fourier names, selection, and closure. """ def __init__(self, *, embedding=None, method="fourier", length=None, normalization="none", center=False, standardize_channels=False, component="amplitude", transform_options=None, selector=None, kinds=("coefficients",), paired=False): self.embedding = embedding self.method = method self.length = length self.normalization = normalization self.center = center self.standardize_channels = standardize_channels self.component = component self.transform_options = transform_options self.selector = selector self.kinds = kinds self.paired = paired def __setstate__(self, state): """Upgrade fitted snapshots saved by the preceding two-interface API.""" super().__setstate__(state) if 'method' in vars(self): for name, value in [('selector', None), ('kinds', ('coefficients',)), ('paired', False)]: if not hasattr(self, name): setattr(self, name, value) if not hasattr(self, 'feature_names_out_'): return if not hasattr(self, 'settings_') and hasattr(self, 'spectrum_length_'): self.length_ = self.spectrum_length_ self.settings_ = dict(method='fourier', length=self.length_, normalization=self.normalization_, center=self.center_) self.component_ = tuple(c for c, enabled in [('amplitude', self.compute_amplitude_), ('phase', self.compute_phase_)] if enabled) self.kinds_ = tuple('coefficients' if k == 'spectra' else 'cross_coefficients' for k in self.spectra_types_) self.coordinates_ = {'frequency': self.frequency_.copy()} self.legacy_, self.paired_ = True, False self.transform_metadata_ = dict(transform='fourier', length=self.length_, normalization=self.normalization_, center=self.center_) elif hasattr(self, 'settings_') and not hasattr(self, 'selected_mask_'): count = len(next(iter(self.coordinates_.values()))) self.selected_mask_ = np.ones(count, dtype=bool) self.kinds_, self.legacy_, self.paired_ = ('coefficients',), False, False self.standardize_channels_ = bool(self.standardize_channels) self.normalization_ = self.settings_['normalization'] self.center_ = self.settings_['center'] self.package_version_ = __version__ def _configuration(self): """Translate constructor settings; compatibility subclasses only adapt this.""" return dict(method=self.method, length=self.length, normalization=self.normalization, center=self.center, standardize=self.standardize_channels, component=self.component, options=self.transform_options, selector=self.selector, kinds=self.kinds, paired=self.paired, legacy=False, embedding=self.embedding)
[docs] def set_params(self, **params): """Change settings and invalidate the fitted schema until the next fit.""" result = super().set_params(**params) if params: self._clear_fit() return result
def _clear_fit(self): """Remove old fitted state before every fit, including unsuccessful refits.""" for name in list(vars(self)): if name.endswith('_') and not name.startswith('_'): delattr(self, name) @staticmethod def _result(sample, embedding, settings, paired, legacy): """Use the common numerical engine, with an optional old closed-bin view.""" result = (transform_pair(*sample, embedding, **settings) if paired else transform_sequence(sample, embedding, **settings)) return result._with_periodic_closure() if legacy else result @staticmethod def _features(result, component, kinds, selector, legacy): """Use the shared export engine for both primary and compatibility names.""" if not legacy: return result.features(component, kinds=kinds, selector=selector) datasets = {kind: (result.coefficients if kind == 'coefficients' else result.cross().coefficients) for kind in kinds} return _export_features(datasets, result.coordinates, 'fourier', component, selector, legacy=True)
[docs] def fit(self, X, y=None): """Freeze training-only grid, channel moments, selection, and column order.""" self._clear_fit() config = self._configuration() validate_preprocessing(config['normalization'], config['center']) if any(not isinstance(config[k], (bool, np.bool_)) for k in ('standardize', 'paired')): raise ValueError('standardize_channels and paired must be booleans') samples = _samples(X, config['paired']) chains = [s for pair in samples for s in pair] if config['paired'] else samples length = _length(config['length'], max(map(len, chains))) embedding = _copy_embedding(b100 if config['embedding'] is None else config['embedding']) means, scales, effective = _channel_statistics(chains, embedding, config['standardize']) options = {} if config['options'] is None else deepcopy(config['options']) allowed = {'radius', 'mellin_c', 'wavelet', 'level', 'mode'} if not isinstance(options, Mapping) or not set(options) <= allowed: raise ValueError(f'transform_options must be a mapping using {sorted(allowed)}') settings = dict(method=config['method'], length=length, normalization=config['normalization'], center=bool(config['center']), **options) result = self._result(samples[0], effective, settings, config['paired'], config['legacy']) mask = _selection(result.coordinates, config['selector']) if not mask.any(): raise ValueError('selector must select at least one coefficient') component, kinds = deepcopy(config['component']), deepcopy(config['kinds']) values, names = self._features(result, component, kinds, mask, config['legacy']) if not names.size or not np.isfinite(values).all(): raise ValueError('select at least one finite output feature') # Commit only after every configuration/schema check has succeeded. self.length_, self.settings_ = length, deepcopy(settings) self.embedding_, self.effective_embedding_ = embedding, effective self.channel_mean_, self.channel_scale_ = means, scales self.component_, self.kinds_ = component, kinds self.selected_mask_ = mask.copy() self.paired_, self.legacy_ = bool(config['paired']), config['legacy'] self.coordinates_ = deepcopy(result.coordinates) self.transform_metadata_ = {k: deepcopy(v) for k,v in result.metadata.items() if k not in ('sequence_length', 'sequence_lengths')} self.feature_names_out_, self.n_features_out_ = names.copy(), len(names) self.package_version_ = __version__ self.standardize_channels_ = bool(config['standardize']) self.normalization_, self.center_ = config['normalization'], bool(config['center']) if config['legacy']: self.spectrum_length_ = length self.frequency_ = self.coordinates_['frequency'].copy() self.selected_frequencies_ = self.frequency_[mask].copy() self.spectra_types_ = tuple('spectra' if k == 'coefficients' else 'cross_spectra' for k in kinds) self.compute_amplitude_ = 'amplitude' in component self.compute_phase_ = 'phase' in component return self
[docs] def transform(self, X): """Apply only frozen settings without changing grids, moments, or selection.""" check_is_fitted(self, ['feature_names_out_', 'settings_']) samples = _samples(X, self.paired_) chains = [s for pair in samples for s in pair] if self.paired_ else samples if max(map(len, chains)) > self.length_: raise ValueError('sequence exceeds fitted length; choose a larger explicit grid and refit') rows = [] for sample in samples: result = self._result(sample, self.effective_embedding_, self.settings_, self.paired_, self.legacy_) values, names = self._features(result, self.component_, self.kinds_, self.selected_mask_, self.legacy_) if not np.array_equal(names, self.feature_names_out_): raise ValueError('computed features do not match fitted schema') rows.append(values) return np.asarray(rows, dtype=float)
[docs] def fit_transform(self, X, y=None, **fit_params): """Materialize generators only once, then use the same fit/transform path.""" if fit_params: raise TypeError('no additional fit parameters are supported') self._clear_fit() samples = _samples(X, self._configuration()['paired']) return self.fit(samples, y).transform(samples)
[docs] def get_feature_names_out(self, input_features=None): """Return independent feature names in output-column order.""" check_is_fitted(self, ['feature_names_out_']) if input_features is not None and len(input_features) != (2 if self.paired_ else 1): raise ValueError('input_features must match the single/paired sequence input') return self.feature_names_out_.copy()
[docs] def get_feature_metadata(self): """Return independent JSON-safe grids, scores, moments, controls, and names.""" check_is_fitted(self, ['feature_names_out_']) return _jsonable(dict(package='Protspect', package_version=self.package_version_, settings=self.settings_, paired=self.paired_, component=self.component_, kinds=self.kinds_, standardize_channels=self.standardize_channels_, embedding=self.embedding_, channel_weighting='one weight per training residue; padding excluded', channel_mean=self.channel_mean_, channel_scale=self.channel_scale_, transform_metadata=self.transform_metadata_, coordinates=self.coordinates_, selected_mask=self.selected_mask_, feature_names=self.feature_names_out_))
[docs] class SpectralTransformer(SequenceTransformer): """Compatibility adapter for the original fitted Fourier feature API. All fitting, transformation, channel preprocessing, and feature extraction delegate to SequenceTransformer. The original constructor, closed frequency grid, ``Amp_``/``Phase_`` feature names, and get_feature_metadata schema are preserved. New code should use SequenceTransformer for every transform. """ def __init__(self, *, embedding=None, spectrum_length=None, normalization="none", center=False, standardize_channels=False, spectra_types=("spectra",), select_method=frequency_select_physical, compute_amplitude=True, compute_phase=False): self.embedding = embedding self.spectrum_length = spectrum_length self.normalization = normalization self.center = center self.standardize_channels = standardize_channels self.spectra_types = spectra_types self.select_method = select_method self.compute_amplitude = compute_amplitude self.compute_phase = compute_phase def _configuration(self): """Translate old argument names and frequency selectors into the shared API.""" for name in ('compute_amplitude', 'compute_phase'): if not isinstance(getattr(self, name), (bool, np.bool_)): raise ValueError(f'{name} must be a boolean') if not self.compute_amplitude and not self.compute_phase: raise ValueError('enable amplitude and/or phase features') kinds = self.spectra_types if (not isinstance(kinds, (list, tuple)) or not kinds or len(set(kinds)) != len(kinds) or any(k not in ('spectra', 'cross_spectra') for k in kinds)): raise ValueError('spectra_types must uniquely select spectra and/or cross_spectra') if not callable(self.select_method): raise ValueError('select_method must be callable') return dict(method='fourier', length=self.spectrum_length, normalization=self.normalization, center=self.center, standardize=self.standardize_channels, embedding=self.embedding, component=tuple(c for c, enabled in [('amplitude', self.compute_amplitude), ('phase', self.compute_phase)] if enabled), options=None, selector=lambda coordinates: self.select_method(coordinates['frequency']), kinds=tuple('coefficients' if k == 'spectra' else 'cross_coefficients' for k in kinds), paired=False, legacy=True) def get_feature_metadata(self): """Preserve the original independent JSON-serializable Fourier provenance.""" check_is_fitted(self, ['feature_names_out_']) return { 'package': 'Protspect', 'package_version': self.package_version_, 'spectrum_length': self.spectrum_length_, 'normalization': self.normalization_, 'center': self.center_, 'standardize_channels': self.standardize_channels_, 'channel_weighting': 'one weight per training residue; padding excluded', 'channel_mean': dict(self.channel_mean_), 'channel_scale': dict(self.channel_scale_), 'embedding': deepcopy(self.embedding_), 'frequency': self.frequency_.tolist(), 'selected_mask': self.selected_mask_.tolist(), 'selected_frequencies': self.selected_frequencies_.tolist(), 'spectra_types': list(self.spectra_types_), 'compute_amplitude': self.compute_amplitude_, 'compute_phase': self.compute_phase_, 'feature_names': self.get_feature_names_out().tolist(), }