"""Unified features for individual sequences, sequence sets, and paired chains."""
import numpy as np
import pandas as pd
from .embeddings import b100
from .utility import frequency_select_physical
from .preprocessing import validate_preprocessing
from ._sequence import _sequences, _length, _attributes, embed_vectors
from .transforms import TransformResult, _transform_vectors, _export_features
[docs]
class Sequence:
"""Encode a sequence using numeric channels and a selectable transform.
Parameters
----------
sequence : str
Nonempty, case-sensitive residue string. All symbols must be present
in every supplied embedding channel; no unknown-residue imputation is done.
attributes : mapping, optional
Metadata exposed as attributes. Names colliding with API or computed
state are rejected.
"""
def __init__(self, sequence, attributes=None):
self.sequence = _sequences([sequence])[0]
reserved = {"sequence", "embeddings", "frequency", "spectrum_length",
"spectra", "cross_spectra", "spectrum_normalization", "spectrum_centered", "result"}
if attributes is not None:
for name, value in attributes.items():
if not isinstance(name, str) or name.startswith('_') or name in reserved or hasattr(self, name):
raise ValueError(f"reserved or invalid attribute name: {name!r}")
setattr(self, name, value)
[docs]
def embed_sequence(self, embeddings):
"""Store one numeric vector per channel from a mapping of mappings.
``embeddings[channel][residue]`` must be a finite real number for
every residue in the sequence. Missing symbols raise ValueError.
Re-embedding invalidates previously computed spectra.
"""
vectors = embed_vectors(self.sequence, embeddings)
self.embeddings = vectors
for name in ("spectra", "cross_spectra", "frequency", "spectrum_length",
"spectrum_normalization", "spectrum_centered", "result"):
self.__dict__.pop(name, None)
def compute_spectra(self, length, *, normalization="none", center=False):
"""Store frequency-centered FFTs after optional signal scaling and padding.
Parameters
----------
length : int
FFT length, at least the sequence length. Each stored spectrum has
``length + 1`` entries: the first centered bin is repeated at the
end for periodic closure. ``frequency`` contains matching cycles
per residue, including the repeated bin shifted by one cycle.
normalization : {"none", "length", "sqrt_length", "energy"}, optional
Divide channel values by 1, residue count N, sqrt(N), or L2 norm,
respectively, before padding. Energy uses the optionally centered
channel; zero-energy channels stay zero. Defaults to raw scaling.
center : bool, optional
Subtract the channel mean over actual residues before scaling and
padding. This is distinct from centering FFT bins with fftshift.
"""
self.compute_transform(length, normalization=normalization, center=center)
self._store_fourier_compatibility()
[docs]
def features(self, component="amplitude", *, kinds=("coefficients",), selector=None):
"""Return values/names using the same export interface for every backend."""
if not hasattr(self, 'result'):
raise ValueError("call compute_transform before features")
return self.result.features(component, kinds=kinds, selector=selector)
def _store_fourier_compatibility(self):
"""Adapt a Fourier result to the historical closed-bin attributes."""
closed = self.result._with_periodic_closure()
self.frequency, self.spectra = closed.coordinates['frequency'], closed.coefficients
self.spectrum_length = self.result.metadata['length']
self.spectrum_normalization = self.result.metadata['normalization']
self.spectrum_centered = self.result.metadata['center']
def _legacy_result(self):
"""Read current compatibility arrays, including explicit caller edits."""
return TransformResult(self.spectra, {'frequency': self.frequency},
{'transform': 'fourier', 'length': self.spectrum_length})
def compute_cross_spectra(self):
"""Store upper-triangle channel products ``X_i * conjugate(X_j)``.
Includes auto-spectra; keys are ``channel_i_channel_j``. Products
inherit both input channels' preprocessing. There is no additional
normalization or statistical averaging of cross-products.
"""
if not hasattr(self, "spectra"):
raise ValueError("call compute_spectra before compute_cross_spectra")
self.cross_spectra = self._legacy_result().cross().coefficients
def compute_spectral_properties(self, spectra_types=("spectra",),
select_method=frequency_select_physical,
compute_amplitude=True, compute_phase=False):
"""Return selected spectral amplitudes and/or phases as a dictionary.
Parameters
----------
spectra_types : iterable of str
``spectra`` and/or ``cross_spectra``, computed beforehand.
select_method : callable
Receives ``frequency`` and returns a same-shape boolean mask.
compute_amplitude, compute_phase : bool
Include absolute magnitudes and/or phases in radians, respectively.
Returns
-------
dict
Scalar features named ``Amp_<channel>_<frequency>`` or
``Phase_<channel>_<frequency>``. Magnitudes inherit preprocessing
from compute_spectra; this export applies no further normalization.
"""
if not hasattr(self, "spectra"):
raise ValueError("call compute_spectra before exporting properties")
datasets = {}
for kind in spectra_types:
if kind not in ("spectra", "cross_spectra") or not hasattr(self, kind):
raise ValueError(f"unavailable spectrum type: {kind!r}")
if kind in datasets:
raise ValueError(f'duplicate spectrum type: {kind}')
datasets[kind] = getattr(self, kind)
components = tuple(name for name, enabled in
[('amplitude', compute_amplitude), ('phase', compute_phase)] if enabled)
values, names = _export_features(datasets, {'frequency': self.frequency},
'fourier', components, lambda c: select_method(c['frequency']), legacy=True)
return dict(zip(names, values))
[docs]
class SequenceFFT(Sequence):
"""Compatibility wrapper for the historical Fourier sequence API.
New code can use Sequence.compute_transform for any backend. compute_spectra
and compute_spectral_properties preserve the original closed bins and names.
"""
def _feature_table(items, component, kinds, selector, attributes):
"""Export generic features with shared coordinates and protected metadata."""
rows, schema = [], None
for item in items:
values, names = item.features(component, kinds=kinds, selector=selector)
if schema is not None and not np.array_equal(names, schema):
raise ValueError('selector produced inconsistent columns across sequences')
schema = names
row = {name: getattr(item, name) for name in (() if attributes is None else attributes)}
if row.keys() & set(names):
raise ValueError('metadata names must not collide with features')
row.update(zip(names, values))
rows.append(row)
return pd.DataFrame(rows)
[docs]
class SequenceSet:
"""Compute features for sequences sharing one embedding and transform grid.
Parameters
----------
embedding : mapping, optional
Channel-to-residue score mappings; defaults to canonical BLOSUM100.
compute_cross_spectra : bool, optional
Compute within-sequence channel cross-products, including auto-spectra.
method : {'fourier', 'z', 'mellin', 'wavelet'}, optional
Transform used by all sequences. Defaults to Fourier.
transform_options : mapping, optional
Backend options such as radius, mellin_c, wavelet, level, and mode.
normalization : {"none", "length", "sqrt_length", "energy"}, optional
Per-channel scaling before transformation.
center : bool, optional
Center each channel over actual residues before scaling and padding.
"""
def __init__(self, embedding=b100, compute_cross_spectra=True, *,
normalization="none", center=False, method="fourier", transform_options=None):
self.method, self.transform_options = method, transform_options
self.embedding = embedding
self.compute_cross_spectra = compute_cross_spectra
validate_preprocessing(normalization, center)
self.normalization = normalization
self.center = center
[docs]
def from_sequence_list(self, sequences, spectrum_length=None, attributes=None, *, length=None):
"""Populate the set from an iterable of nonempty sequence strings.
``length`` defaults to the smallest power of two covering the longest
sequence. ``spectrum_length`` is the compatibility spelling; do not
provide both. ``attributes`` maps metadata names to equal-length
columns, one value per sequence. Mutates this object and returns None.
"""
for name in ('sequences', 'spectrum_length', 'length', 'monomers', 'results'):
self.__dict__.pop(name, None)
if length is not None and spectrum_length is not None:
raise ValueError('use length or the compatibility spectrum_length, not both')
sequences = _sequences(sequences)
length = _length(length if length is not None else spectrum_length, max(map(len, sequences)))
rows = _attributes(attributes, len(sequences))
monomers = []
for sequence, row in zip(sequences, rows):
item_class = SequenceFFT if self.method == 'fourier' else Sequence
item = item_class(sequence, row)
item.embed_sequence(self.embedding)
item.compute_transform(length, method=self.method, normalization=self.normalization,
center=self.center, **(self.transform_options or {}))
if self.method == 'fourier':
item._store_fourier_compatibility()
if self.compute_cross_spectra:
item.compute_cross_spectra()
monomers.append(item)
self.sequences, self.spectrum_length, self.monomers = sequences, length, monomers
self.results = [item.result for item in monomers]
self.length = length
[docs]
def export_features(self, component="amplitude", *, kinds=("coefficients",),
selector=None, attributes=None):
"""Return a DataFrame for any backend using TransformResult.features.
All sequences share one grid. selector receives a coordinate dictionary;
kinds can include aligned within-sequence cross_coefficients. Metadata
columns must not collide with feature names. Populate the set first.
"""
if not hasattr(self, 'monomers'):
raise ValueError('call from_sequence_list before export_features')
return _feature_table(self.monomers, component, kinds, selector, attributes)
[docs]
def export_datatable(self, spectra=("spectra",), attributes=None,
select_method=frequency_select_physical,
compute_amplitude=True, compute_phase=False):
"""Return a pandas DataFrame with one row per sequence.
``spectra`` chooses computed spectrum types. ``attributes`` lists metadata
columns to copy; selectors and amplitude/phase flags follow
:meth:`SequenceFFT.compute_spectral_properties`. Populate the set first.
"""
if not hasattr(self, "monomers"):
raise ValueError("call from_sequence_list before export_datatable")
if not hasattr(self.monomers[0], 'frequency'):
raise ValueError('legacy frequency export is Fourier-only; use export_features')
return _datatable(self.monomers, spectra, attributes, select_method,
compute_amplitude, compute_phase)
def _datatable(items, spectra, attributes, selector, amplitude, phase):
"""Export items without allowing metadata to overwrite spectral features."""
rows = []
for item in items:
row = {name: getattr(item, name) for name in (() if attributes is None else attributes)}
features = item.compute_spectral_properties(spectra, selector, amplitude, phase)
if row.keys() & features.keys():
raise ValueError("metadata names must not collide with spectral features")
row.update(features)
rows.append(row)
return pd.DataFrame(rows)
[docs]
class ComplexSet:
"""Compute ordered cross-chain products for paired sequences.
``embedding`` defaults to BLOSUM100. The historical
``compute_cross_cross_spectra`` option is unimplemented; True raises
NotImplementedError rather than silently doing nothing. ``normalization``
and ``center`` follow SequenceFFT.compute_spectra and are applied to each
chain independently before cross-products. method selects fourier, z,
mellin, or wavelet; transform_options supplies the backend options. Use
export_features for every backend. export_datatable is a Fourier-only
compatibility adapter with the original frequency selectors and names.
"""
def __init__(self, embedding=b100, compute_cross_cross_spectra=False, *,
normalization="none", center=False, method="fourier", transform_options=None):
self.method, self.transform_options = method, transform_options
if compute_cross_cross_spectra:
raise NotImplementedError("cross-cross spectra are not implemented")
self.embedding = embedding
self.compute_cross_cross_spectra = compute_cross_cross_spectra
validate_preprocessing(normalization, center)
self.normalization = normalization
self.center = center
[docs]
def from_sequence_list(self, A_sequences, B_sequences, spectrum_length=None, attributes=None, *, length=None):
"""Populate equally sized collections of paired A/B sequence strings.
All chains share ``length`` (or compatibility ``spectrum_length``),
defaulting to the smallest power of two covering the longest chain. Attribute columns have one value per pair.
``A`` and ``B`` store chain results; ``AB`` stores every ordered channel
product after each chain's preprocessing. Fourier compatibility attributes
are also available when method='fourier'.
"""
for name in ('A_sequences', 'B_sequences', 'spectrum_length', 'length', 'A', 'B', 'AB', 'results'):
self.__dict__.pop(name, None)
if length is not None and spectrum_length is not None:
raise ValueError('use length or the compatibility spectrum_length, not both')
a_sequences, b_sequences = _sequences(A_sequences), _sequences(B_sequences)
if len(a_sequences) != len(b_sequences):
raise ValueError("A_sequences and B_sequences must have equal lengths")
length = _length(length if length is not None else spectrum_length,
max(map(len, a_sequences + b_sequences)))
rows = _attributes(attributes, len(a_sequences))
a_items, b_items, pairs = [], [], []
for a, b, row in zip(a_sequences, b_sequences, rows):
item_class = SequenceFFT if self.method == 'fourier' else Sequence
first, second = item_class(a, row), item_class(b, row)
for item in (first, second):
item.embed_sequence(self.embedding)
item.compute_transform(length, method=self.method, normalization=self.normalization,
center=self.center, **(self.transform_options or {}))
if self.method == 'fourier':
item._store_fourier_compatibility()
pair = item_class(a, row)
pair.sequence = (a, b)
pair.result = first.result.cross(second.result)
if self.method == 'fourier':
pair._store_fourier_compatibility()
a_items.append(first)
b_items.append(second)
pairs.append(pair)
self.A_sequences, self.B_sequences = a_sequences, b_sequences
self.spectrum_length = length
self.A, self.B, self.AB = a_items, b_items, pairs
self.results = [item.result for item in pairs]
self.length = length
[docs]
def export_features(self, component="amplitude", *, chain_ID="AB", kinds=("coefficients",),
selector=None, attributes=None):
"""Export either chain or ordered A/B coefficient products for any backend.
chain_ID is A, B, or AB. Paired products use every A/B channel combination;
wavelet products remain band/position features, not Fourier cross-spectra.
"""
if chain_ID not in ('A', 'B', 'AB'):
raise ValueError("chain_ID must be 'A', 'B', or 'AB'")
if not hasattr(self, 'AB'):
raise ValueError('call from_sequence_list before export_features')
return _feature_table(getattr(self, chain_ID), component, kinds, selector, attributes)
[docs]
def export_datatable(self, chain_ID="AB", attributes=None,
select_method=frequency_select_physical,
compute_amplitude=True, compute_phase=False):
"""Return a feature DataFrame for ``chain_ID`` A, B, or AB.
``attributes`` lists metadata columns; frequency selection and feature
flags follow :meth:`SequenceFFT.compute_spectral_properties`.
Populate the paired set before calling this method.
"""
if chain_ID not in ("A", "B", "AB"):
raise ValueError("chain_ID must be 'A', 'B', or 'AB'")
if not hasattr(self, "AB"):
raise ValueError("call from_sequence_list before export_datatable")
if not hasattr(self.AB[0], 'frequency'):
raise ValueError('legacy frequency export is Fourier-only; use export_features')
return _datatable(getattr(self, chain_ID), ("spectra",), attributes,
select_method, compute_amplitude, compute_phase)