Representations and selectors

Built-in channels

protspect.embeddings.b100 is the read-only corrected 20-channel BLOSUM100 mapping. protspect.embeddings.kidera is the read-only ten-factor mapping. Use the factory below for independent dictionaries, including sklearn cloning.

protspect.embeddings.kidera_factors()[source]

Return independent residue mappings for the ten published Kidera factors.

Channels KF1–KF10 cover the 20 canonical amino acids in published order at two-decimal source precision. No extra scaling, averaging, or unknown residue imputation is applied. Fresh dictionaries support customization, estimator cloning, and serialization without changing the built-in table.

Reference: Kidera et al. (1985), Journal of Protein Chemistry 4, 23–55, doi:10.1007/BF01025492. See docs/REPRESENTATIONS.md for table provenance.

AAindex catalogues

No catalogue is downloaded at import time. Keep local inputs and hashes.

class protspect.aaindex.AAIndex(entries, *, sha256, source_path, source_url=None, version=None)[source]

Read-only catalogue of AAindex1 records; load files explicitly with from_file.

Entries may contain missing values; embedding conversion requires complete entries. No implicit scaling, imputation, filtering, or network access occurs.

classmethod from_file(path, *, expected_sha256=None, source_url=None, version=None)[source]

Read a local UTF-8 file for this catalogue section, optionally pinning SHA256.

source_url and version are caller-supplied provenance labels: AAindex records do not declare a database version. The source path and actual raw-byte checksum are always recorded. This method never downloads data.

search(query, *, complete_only=False)[source]

Return records matching a case-insensitive substring of citation or description.

embedding(accessions)[source]

Return fresh channel-to-residue dictionaries in requested accession order.

Each accession names one channel. Published values are unchanged. Incomplete entries raise ValueError listing the missing residues; no imputation is performed. Unknown accessions raise KeyError. Returned mappings support Protspect core classes and scikit-learn estimators.

metadata(accessions)[source]

Return JSON-compatible provenance and full selected source values.

Export this together with fitted preprocessing metadata. Missing source values remain None (JSON null); incomplete entries can be inspected without converting them into an embedding.

class protspect.aaindex.AAIndexEntry(accession, description, scores, authors='', title='', journal='', references='', comments='', correlations='')[source]

One AAindex1 property and its literature metadata.

scores follows ARNDCQEGHILKMFPSTWYV, with None for published NA values. values exposes a read-only residue mapping; metadata preserves source text without interpreting units or treating correlations as interchangeable indices.

Parameters:
  • accession (str)

  • description (str)

  • scores (tuple)

  • authors (str)

  • title (str)

  • journal (str)

  • references (str)

  • comments (str)

  • correlations (str)

property values

Read-only canonical residue values, including explicit missing values.

property missing_residues

Canonical residues lacking a published value, in canonical order.

property complete

Whether all twenty canonical residues have finite published values.

class protspect.aaindex.AAIndex2(entries, *, sha256, source_path, source_url=None, version=None)[source]

Offline AAindex2 substitution matrix catalogue, loaded with from_file().

embedding(accessions, *, axis)

Convert selected canonical submatrices into explicit row/column profiles.

axis=’rows’: channel ‘<ID>_rows_A’ maps residue R to M[A,R]. axis=’columns’: channel ‘<ID>_columns_A’ maps residue R to M[R,A]. Every matrix produces twenty channels in ARNDCQEGHILKMFPSTWYV order, each covering that same canonical input alphabet. Extra symbols remain available in the catalogue but are omitted from this canonical adapter. Incomplete canonical blocks raise ValueError. No averaging, scaling, imputation, or symmetrization of full matrices is performed. Returned ordinary dictionaries support estimator cloning and serialization.

classmethod from_file(path, *, expected_sha256=None, source_url=None, version=None)

Read a local UTF-8 file for this catalogue section, optionally pinning SHA256.

source_url and version are caller-supplied provenance labels: AAindex records do not declare a database version. The source path and actual raw-byte checksum are always recorded. This method never downloads data.

metadata(accessions, *, axis=None)

Export source matrices and optionally the exact canonical profile schema.

With axis=None, incomplete/native records remain inspectable. Supply the same explicit axis used for embedding() to record derived channel names, orientation, and canonical-submatrix policy alongside the source. Full axes and expanded values are always retained with the raw-file hash.

search(query, *, complete_only=False)

Return records matching a case-insensitive substring of citation or description.

class protspect.aaindex.AAIndex3(entries, *, sha256, source_path, source_url=None, version=None)[source]

Offline AAindex3 contact-potential catalogue, loaded with from_file().

Matrix-derived profile channels are sequence representations. Computing their Fourier spectra does not infer structural contacts or contact energies.

embedding(accessions, *, axis)

Convert selected canonical submatrices into explicit row/column profiles.

axis=’rows’: channel ‘<ID>_rows_A’ maps residue R to M[A,R]. axis=’columns’: channel ‘<ID>_columns_A’ maps residue R to M[R,A]. Every matrix produces twenty channels in ARNDCQEGHILKMFPSTWYV order, each covering that same canonical input alphabet. Extra symbols remain available in the catalogue but are omitted from this canonical adapter. Incomplete canonical blocks raise ValueError. No averaging, scaling, imputation, or symmetrization of full matrices is performed. Returned ordinary dictionaries support estimator cloning and serialization.

classmethod from_file(path, *, expected_sha256=None, source_url=None, version=None)

Read a local UTF-8 file for this catalogue section, optionally pinning SHA256.

source_url and version are caller-supplied provenance labels: AAindex records do not declare a database version. The source path and actual raw-byte checksum are always recorded. This method never downloads data.

metadata(accessions, *, axis=None)

Export source matrices and optionally the exact canonical profile schema.

With axis=None, incomplete/native records remain inspectable. Supply the same explicit axis used for embedding() to record derived channel names, orientation, and canonical-submatrix policy alongside the source. Full axes and expanded values are always retained with the raw-file hash.

search(query, *, complete_only=False)

Return records matching a case-insensitive substring of citation or description.

class protspect.aaindex.AAIndexMatrixEntry(accession, description, rows, columns, scores, storage, authors='', title='', journal='', references='', comments='', correlations='')[source]

An AAindex2/3 matrix with original axes and literature metadata.

scores is an immutable tuple of row tuples. NA and standalone - remain None. Only lower-triangle input is reflected to reconstruct symmetry; full matrices retain direction and rectangular shape, including extra residue symbols.

Parameters:
  • accession (str)

  • description (str)

  • rows (str)

  • columns (str)

  • scores (tuple)

  • storage (str)

  • authors (str)

  • title (str)

  • journal (str)

  • references (str)

  • comments (str)

  • correlations (str)

property values

Read-only mappings indexed first by row residue, then column residue.

property shape

Original row and column dimensions, including noncanonical symbols.

property missing_pairs

Ordered (row, column) pairs with missing source scores.

property complete

Whether every cell of the full native matrix is present.

property canonical_complete

Whether the canonical 20-by-20 submatrix exists and is complete.

protspect.aaindex.download_aaindex1(path, *, expected_sha256=None, timeout=30)[source]

Download/validate official AAindex1 into a new file; return an AAIndex catalogue.

Never overwrite an existing file. Reuse it offline with AAIndex.from_file. An optional SHA256 pin enforces exact source bytes before any cache write.

protspect.aaindex.download_aaindex2(path, *, expected_sha256=None, timeout=30)[source]

Download/validate official AAindex2 into a new file; return an AAIndex2 catalogue.

Existing files are never overwritten. Reuse snapshots offline with from_file.

protspect.aaindex.download_aaindex3(path, *, expected_sha256=None, timeout=30)[source]

Download/validate official AAindex3 into a new file; return an AAIndex3 catalogue.

Existing files are never overwritten. Reuse snapshots offline with from_file.

Frequency helpers

Wrap these in a coordinate-dictionary selector for the primary API, for example selector=lambda c: frequency_select_positive(c['frequency']). They are not wavelet band or Mellin log-frequency selectors.

protspect.utility.frequency_select_physical(freq)[source]

Select DC and positive dyadic frequencies (1/2, 1/4, …).

Parameters:

freq (array-like of float) – One-dimensional frequency grid in cycles per residue.

Returns:

Mask selecting grid points equal, within floating-point tolerance, to zero or reciprocal powers of two resolvable on the grid. For grids without dyadic bins, only DC may be selected.

Return type:

numpy.ndarray of bool

protspect.utility.frequency_select_positive(freq)[source]

Return a boolean mask selecting nonnegative frequencies, including DC.