Interaction

Interaction implementations.

Hydrophobic / Polar (HP) interaction model.

This module provides HPInteraction which:

  • loads a simple text file mapping residue one-letter symbols to a binary

    hydrophobic(1)/polar(0) flag,

  • exposes the list of hydrophobic symbols, and

  • provides a pairwise energy function where only hydrophobic-hydrophobic

    contacts contribute (default energy -1.0) while any pair involving a polar residue contributes 0.0.

HP matrix file format

Expected file (e.g. hp_matrix.txt) structure:

A 1 R 0 N 0 …

Columns are separated by arbitrary whitespace. Only the first two tokens on a line are considered: the residue symbol (single character) and a flag (0 or 1).

HP Symmetry / Energies

The classical lattice HP model assigns the same energy to any hydrophobic-hydrophobic contact independent of residue identities (here set to -1.0). All other pairs have energy 0.0.

class interaction.hp_interaction.HPInteraction(interaction_matrix_path=HP_INTERACTION_MATRIX_FILEPATH)

Bases: Interaction

Interaction model implementing the classical Hydrophobic/Polar (HP) scheme.

Loads a binary HP matrix, tracks hydrophobic symbols, and provides a pairwise energy function where only H-H contacts contribute negatively.

__init__(interaction_matrix_path=HP_INTERACTION_MATRIX_FILEPATH)

Initialize the HP interaction model by loading hydrophobic residues from the HP matrix file and preparing the supported symbol set.

Parameters:

interaction_matrix_path (Path, optional) – Path to the HP interaction matrix file. Defaults to HP_INTERACTION_MATRIX_FILEPATH.

_abc_impl = <_abc._abc_data object>
_is_hydrophobic(symbol)

Check if an amino acid symbol is hydrophobic.

Return type:

bool

Parameters:

symbol (str) – Single-letter amino acid symbol.

Returns:

True if the symbol is hydrophobic, False otherwise.

Return type:

bool

_load_hp_symbols(hp_filepath=HP_INTERACTION_MATRIX_FILEPATH)

Load hydrophobic amino acid symbols from a HP interaction matrix file.

Parses a small, strict matrix file where each line has the format ‘<SYMBOL> <0|1>’. Ignores blank lines and lines starting with ‘#’. Lines with ‘1’ indicate hydrophobic residues.

Return type:

tuple[list[str], list[str]]

Parameters:

hp_filepath (Path, optional) – Path to the HP interaction matrix file. Defaults to HP_INTERACTION_MATRIX_FILEPATH.

Returns:

Tuple containing lists of hydrophobic and polar amino acid symbols.

Return type:

tuple[list[str], list[str]]

Raises:

Exception – If the HP matrix file cannot be read or parsed.

get_energy(symbol_i, symbol_j)

Return the HP model pair energy.

Returns the hydrophobic-hydrophobic contact energy (HP_HH_CONTACT_ENERGY) if both residues are hydrophobic, otherwise returns the non-hydrophobic contact energy (HP_NON_HH_CONTACT_ENERGY).

Return type:

float

Parameters:

  • symbol_i (str) – Single-letter amino acid symbol for the first residue.

  • symbol_j (str) – Single-letter amino acid symbol for the second residue.

Returns:

Interaction energy according to the HP model.

Return type:

float

Raises:

UnsupportedAminoAcidSymbolError – If either residue symbol is not in the HP matrix.

Interaction models for protein folding.

Defines the abstract base class Interaction, which loads an interaction matrix and computes interaction energies used in folding models such as HP or MJ.

class interaction.interaction.Interaction(interaction_matrix_path)

Bases: ABC

Abstract base class for interaction models.

Subclasses must implement get_energy to return a numeric energy value and define their own initialization logic. Subclasses should also manage to properly set the valid_symbols set to determine which amino acid symbols they support.

Variables:

valid_symbols (set[str]) – Set of valid amino acid symbols for the interaction model.

__init__(interaction_matrix_path)

Initialize the interaction model.

Parameters:

interaction_matrix_path (Path) – Path to the file containing the interaction matrix.

_abc_impl = <_abc._abc_data object>
abstractmethod get_energy(symbol_i, symbol_j)

Compute and return the interaction energy.

This method must be implemented by all subclasses.

Return type:

float

Returns:

Calculated interaction energy.

Return type:

float

Miyazawa-Jernigan (MJ) pairwise contact potentials.

This module provides a small utility class, MJInteraction, that:

  • loads an MJ interaction matrix from a plain-text file,

  • records the set of valid residue symbols (one-letter codes), and

  • builds a dictionary that maps residue-residue pairs (e.g., “AL”, “LA”) to their contact energies.

MJ matrix format assumptions

The file is expected to contain a header row with one-letter residue symbols. Starting from the second row, each row begins with a residue symbol and the upper triangle (including the diagonal) of energies is provided. The loader mirrors values to create a symmetric mapping, so both “AB” and “BA” keys are present with the same energy.

class interaction.mj_interaction.MJInteraction(interaction_matrix_path=MJ_INTERACTION_MATRIX_FILEPATH)

Bases: Interaction

MJ interaction model that loads the MJ matrix and exposes pairwise residue contact energies.

Variables:

valid_symbols (set[str]) – Set of valid amino acid symbols for the interaction model.

__init__(interaction_matrix_path=MJ_INTERACTION_MATRIX_FILEPATH)

Initialize MJInteraction instance.

Loads the MJ interaction matrix from a file and prepares a mapping of residue-residue pairs to their contact energies.

Parameters:

interaction_matrix_path (Path) – Path to the MJ interaction matrix file. Defaults to MJ_INTERACTION_MATRIX_FILEPATH.

_abc_impl = <_abc._abc_data object>
_prepare_mj_interaction_matrix(mj_filepath=MJ_INTERACTION_MATRIX_FILEPATH)

Prepare the MJ interaction matrix.

Reads the MJ matrix file, records valid residue symbols, and builds a dictionary of symmetric residue-residue contact energies.

Return type:

dict[str, float]

Parameters:

mj_filepath (Path) – Path to the MJ matrix file. Defaults to MJ_INTERACTION_MATRIX_FILEPATH.

Returns:

Dictionary mapping residue pair codes to energies.

Return type:

dict[str, float]

Raises:

Exception – If an error occurs while loading or parsing the matrix.

get_energy(symbol_i, symbol_j)

Return MJ interaction energy for a pair of residue symbols.

Return type:

float

Parameters:

  • symbol_i (str) – One-letter code of the first residue.

  • symbol_j (str) – One-letter code of the second residue.

Returns:

MJ interaction energy between the two residues.

Return type:

float

Raises:

UnsupportedAminoAcidSymbolError – If either residue symbol is not in the MJ matrix.