Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Protspect

Protein sequence spectral analysis: Fourier features for proteins and peptides using numeric residue-property channels. This is the original sequence featurization method, separate from the subsequent protein language-model work.

The repository is biomodsquad/protein-sequence-spectral-analysis. The planned PyPI distribution is Protspect, imported as protspect. The original ProSpect distribution name conflicts with an unrelated existing PyPI package. This is an alpha release candidate; no release has been uploaded by this change.

Install locally

Requires Python 3.10 or later and NumPy, SciPy, and pandas.

git clone https://github.com/biomodsquad/protein-sequence-spectral-analysis.git
cd protein-sequence-spectral-analysis
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

Until the first release is published, install from this checkout. Do not install prospect from PyPI expecting this library.

Generate sequence features

from protspect import SequenceSet

features = SequenceSet(compute_cross_spectra=False)
features.from_sequence_list(
    ["ACDE", "ACDF"],
    spectrum_length=8,
    attributes={"name": ["peptide-1", "peptide-2"]},
)
table = features.export_datatable(attributes=["name"])
print(table.shape)  # (2, 81): metadata plus 20 channels at four frequencies

The default embedding protspect.embeddings.b100 maps 20 canonical amino acids to their 20 BLOSUM100 substitution-score channels. Inputs are case-sensitive; unknown residues, gaps, stop symbols, and lowercase letters are rejected when not covered by the embedding. Custom numeric channels can encode other residue properties or alphabets:

from protspect import SequenceFFT

sequence = SequenceFFT("ACAC")
sequence.embed_sequence({"property": {"A": 1.0, "C": -1.0}})
sequence.compute_spectra(length=4)
properties = sequence.compute_spectral_properties(compute_phase=True)
assert properties["Amp_property_0.5"] == 4.0

embed_sequence stores one numeric vector per channel; compute_spectra right-pads each vector with zeros and computes its FFT. compute_cross_spectra optionally creates all upper-triangle within-sequence channel cross-products, including auto-spectra. To export those, use features.export_datatable(spectra=("cross_spectra",)) after enabling them. Metadata names must not collide with API attributes or generated feature names.

Paired chains

from protspect import ComplexSet

pairs = ComplexSet()
pairs.from_sequence_list(["ACDE"], ["ACDF"], spectrum_length=8)
cross_chain_features = pairs.export_datatable(chain_ID="AB")
chain_a_features = pairs.export_datatable(chain_ID="A")

A/B collections must contain the same number of sequences. Each pair produces all ordered channel products FFT(A_i) * conjugate(FFT(B_j)). Swapping A and B conjugates the corresponding product, so phase encodes chain order. These are spectral descriptors, not a physical model of binding or residue contacts. compute_cross_cross_spectra=True is explicitly unsupported.

Numerical conventions

  • All sequences in a collection share one FFT length. If omitted, the next power of two covering the longest sequence is used. Supply the same explicit length for training, validation, and test collections to preserve columns.
  • FFTs are unnormalized by default and their bins are centered with fftshift. For FFT length L, spectrum_length is L, while each stored spectrum and its frequency array contain L + 1 entries. The first bin is repeated at the end to close the periodic spectrum, with its frequency increased by one cycle per residue. For even L, this gives frequencies from -0.5 through +0.5. For odd L, the endpoint exceeds +0.5; it remains a periodic duplicate, not a new bin.
  • The default selector exports DC and positive dyadic frequencies on the grid: 1/2, 1/4, 1/8, etc. For non-power-of-two lengths some or all dyadic bins may be absent. A custom selector receives the frequency array and must return a boolean mask of the same shape. frequency_select_positive in protspect.utility selects all nonnegative entries, including the closure bin.
  • Amp_... features are absolute magnitudes; Phase_... features are angles in radians. Cross-spectrum magnitudes scale quadratically with signal scale. Optional length, square-root-length, or unit-energy scaling and per-sequence mean centering are available before padding. No preprocessing is applied by default, and phase unwrapping is not implemented. Phase at zero magnitude is not meaningful.
  • Padding, sequence length, and channel scale affect the representation. Amplitudes lose absolute circular-shift position information; phases depend on alignment and sequence origin. Standardize features using training data only when fitting downstream models.

Normalization and fitted grids

SequenceFFT.compute_spectra, SequenceSet, and ComplexSet accept explicit normalization='none'|'length'|'sqrt_length'|'energy' and center=False|True options. Existing raw defaults are preserved.

For machine learning, install .[ml] and use from protspect.sklearn import SpectralTransformer inside a scikit-learn Pipeline. It freezes the grid, selector, embedding, and feature column order at fit time, and can learn channel scales from training residues only. Longer prediction sequences raise an error rather than changing the grid. See the preprocessing guide for formulas, tradeoffs, leakage prevention, and model/feature metadata persistence.

Migration from FFTpro

FFTpro.features, FFTpro.embeddings, and FFTpro.utility remain compatibility imports. New code should use protspect. The misspelled selector frequency_selelect_positive is retained as an alias.

Feature values have intentionally changed. The original implementation labeled unshifted FFT coefficients using a centered grid, assigning coefficients to incorrect frequencies. The corrected implementation aligns bins and labels. The BLOSUM100 P-to-A score was also corrected from +2 to -2, matching A-to-P. Regenerate existing feature tables and retrain downstream models; old and new features must not be mixed. Empty sequences, short FFT lengths, unequal pair counts, and unequal metadata lengths now raise errors instead of failing later or silently dropping records.

The historical notebook in FFTpro/examples/ is archived with all saved outputs cleared; the original CPP CSVs remain unchanged and excluded from distributions. A new reproducible CPP notebook and workflow uses the complete official MLCPP 2.0 website datasets and a pinned MISTIC source, a separate locked research environment, training-only model selection, exact train/test overlap checks, and recorded provenance. See executed results and official data preparation and provenance. Research dependencies are optional and separate from the runtime package. Use examples/basic_features.py for a minimal core-only example.

Development and release

python -m pytest -q
python -m ruff check .
python -m build
python -m twine check dist/*

For the controlled antimicrobial-peptide correction audit, see validation/README.md. Install .[dev,validation] to run its classifier tests and benchmark.

CI checks Python 3.10–3.15 on Linux, macOS, and Windows, installing both wheel and source archives into fresh environments outside the checkout. Exact minimum dependencies are checked on Python 3.10. See the compatibility policy for scope and evidence. See RELEASE_REVIEW.md for findings, validation evidence, and the remaining release decisions. The initial alpha version is 0.1.0a1. Name availability is not a reservation; confirm it and complete TestPyPI installation checks before uploading to PyPI.

Citation and project contact

Cite the software version and commit used:

Biomolecular Systems Modeling and Design Group. Protspect: protein sequence spectral analysis. Version 0.1.0a1. https://github.com/biomodsquad/protein-sequence-spectral-analysis

Machine-readable metadata is in CITATION.cff. Cite dataset sources and external methods separately; the CPP example lists these in its provenance documentation.

The group maintains this package through GitHub Issues. See the changelog, support policy, and contribution guide.

Licensed under the BSD 3-Clause License.

Metadata

Release files for Protspect 0.1.0a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for Protspect 0.1.0a1
File Size Uploaded Provenance Actions
protspect-0.1.0a1.tar.gz 64.2 kB With provenance Details for protspect-0.1.0a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for Protspect 0.1.0a1
File Interpreter ABI Platform Actions
protspect-0.1.0a1-py3-none-any.whl Python 3 none any Details for protspect-0.1.0a1-py3-none-any.whl

Total release size: 84.7 kB

Release files / protspect-0.1.0a1.tar.gz

Download URL protspect-0.1.0a1.tar.gz
Size 64.2 kB
Tags Source
SHA-256 checksum
How to use checksums
3aa3edbe4c0c31c62bb2081546a67968e22c7d0e0aade77f7bb38a2398d47fe2
BLAKE2b-256 checksum
How to use checksums
5afbbdf55e47fa429dbe2c59dede600c5546d889259330af3cebcb639affb790
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / protspect-0.1.0a1-py3-none-any.whl

Download URL protspect-0.1.0a1-py3-none-any.whl
Size 20.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
71d49afe8e14b51f1dc1aade429acfdddc7f74a6360d4e8109b0cd1db21bd7cc
BLAKE2b-256 checksum
How to use checksums
cf4d3a3fe70dc1341005441aabac0e533acb54177a77ec14e6a229ffdecad98e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for Protspect 0.1.0a1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for protspect-0.1.0a1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page