Skip to content

Functional API

lahuta.contacts.F

The main entry point for users to access the various functionalities of the contacts package. It imports all necessary functions for computing interactions, thus providing an easy and concise way to use the package's functionalities.

Each function takes a NeighborPairs object, which represents precomputed neighbor relationships between atoms, and an optional distance cutoff parameter for certain types of contacts. Each function returns a new NeighborPairs object that represents the specific contacts computed by that function.

Notes

Each atomic contact type is computed based on a set of conditions, primarily involving the types of the two interacting atoms and the distance between them. For example, carbonyl contacts are calculated by filtering for neighbor pairs where one atom is a carbonyl oxygen and the other is a carbonyl carbon, and the distance between them is less than a predefined cutoff.

Most contact calculation functions also accept a distance argument specifying the cutoff distance for considering two atoms as neighbors in the contact type calculation. These cutoffs are defined in the lahuta.config.defaults module and can be adjusted as per user requirements.

Example 
from lahuta.contacts import F

# Define your system and compute neighbors
luni = Luni(...)
ns = luni.compute_neighbors()

# Compute aromatic neighbors
aromatic_nbs = F.aromatic_neighbors(ns)

# Compute hydrophobic neighbors
hydrophobic_nbs = F.hydrophobic_neighbors(ns)

# Compute ionic neighbors
ionic_nbs = F.ionic_neighbors(ns)

# Compute plane-plane neighbors
pp_nbs = F.plane_plane_neighbors(ns)

covalent_neighbors 

covalent_neighbors(ns)

Handle the computation of covalent contacts in a molecular system.

Covalent contacts are interactions based on covalent bonds between atoms in a molecular system. This class, a derivative of the ContactAnalysis base class, overrides the compute method to provide functionality specifically for covalent contact computation.

Covalent contacts refer to the interactions between atoms that share an electron pair, forming a covalent bond. We use the OpenBabel library to identify covalent bonds in the structure.

Definition

Two atoms are considered to form a covalent contact if they are covalently bonded according to the molecular structure information obtained from OpenBabel.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required

Returns:

Type Description
NeighborPairs

A NeighborPairs object containing only covalent contacts.
Source code in lahuta/contacts/contacts.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def covalent_neighbors(ns: NeighborPairs) -> NeighborPairs:
    """Handle the computation of covalent contacts in a molecular system.

    Covalent contacts are interactions based on covalent bonds between atoms in a molecular system.
    This class, a derivative of the `ContactAnalysis` base class, overrides the `compute` method
    to provide functionality specifically for covalent contact computation.

    Covalent contacts refer to the interactions between atoms that share an electron pair, forming a covalent bond.
    We use the OpenBabel library to identify covalent bonds in the structure.

    !!! tip "Definition"
        Two atoms are considered to form a covalent contact if they are covalently bonded according to the molecular
        structure information obtained from OpenBabel.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.

    Returns:
        (NeighborPairs): A NeighborPairs object containing only covalent contacts.
    """
    bonds = get_bonded_atoms(ns.mol)
    indices = find_shared_pairs(ns.pairs + 1, bonds)

    return ns.clone(ns.pairs[indices], ns.distances[indices])

metalic_neighbors 

metalic_neighbors(ns, distance=CONTACTS['metal']['distance'])

Handle the computation of metallic contacts in a molecular system.

Metallic contacts are interactions involving metal atoms in a molecular system. This class, a derivative of the ContactAnalysis base class, overrides the compute method to provide functionality specifically for metallic contact computation.

Metallic contacts are interactions between metal ions and atoms that can act as hydrogen bond acceptors. These contacts play significant roles in the structure and function of many proteins, especially metalloproteins. Metal ions can form coordination bonds with electron-rich atoms (like oxygen, nitrogen, or sulfur), contributing to the structural stability and sometimes the catalytic activity of these proteins.

Definition

  1. The contact involves a metal ion and an atom that is a hydrogen bond acceptor.
  2. The distance between the metal ion and the hydrogen bond acceptor does not exceed the predefined distance cutoff.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
distance float

The maximum distance to consider for a metallic contact. This value is retrieved from the 'metal' entry of the global CONTACTS dictionary.

 CONTACTS['metal']['distance']

Returns:

Type Description
NeighborPairs

A NeighborPairs object containing only metallic contacts.
Source code in lahuta/contacts/contacts.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def metalic_neighbors(ns: NeighborPairs, distance: float = CONTACTS["metal"]["distance"]) -> NeighborPairs:
    """Handle the computation of metallic contacts in a molecular system.

    Metallic contacts are interactions involving metal atoms in a molecular system.
    This class, a derivative of the `ContactAnalysis` base class, overrides the `compute`
    method to provide functionality specifically for metallic contact computation.

    Metallic contacts are interactions between metal ions and atoms that can act as hydrogen bond acceptors.
    These contacts play significant roles in the structure and function of many proteins, especially metalloproteins.
    Metal ions can form coordination bonds with electron-rich atoms (like oxygen, nitrogen, or sulfur),
    contributing to the structural stability and sometimes the catalytic activity of these proteins.

    !!! tip "Definition"
        1. The contact involves a metal ion and an atom that is a hydrogen bond acceptor.
        2. The distance between the metal ion and the hydrogen bond acceptor \
            does not exceed the predefined distance cutoff.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        distance (float): The maximum distance to consider for a metallic contact. This value is retrieved
            from the 'metal' entry of the global CONTACTS dictionary.

    Returns:
        (NeighborPairs): A NeighborPairs object containing only metallic contacts.
    """
    metal_indices = ns.atoms.select_atoms("element " + " ".join(METALS)).indices

    acceptor_metal = ns.type_filter("hbond_acceptor", 1).index_filter(metal_indices, 2).distance_filter(distance)

    metal_acceptor = ns.type_filter("hbond_acceptor", 2).index_filter(metal_indices, 1).distance_filter(distance)

    return acceptor_metal + metal_acceptor

carbonyl_neighbors 

carbonyl_neighbors(ns, distance=CONTACTS['carbonyl']['distance'])

Handle the computation of carbonyl contacts in a molecular system.

Carbonyl contacts involve the interaction between a carbonyl oxygen atom (O) and a carbonyl carbon atom (C) from a carbonyl functional group (C=O) in the context of protein-ligand structures or protein-protein structures.

In a carbonyl group, the carbon atom has a double bond with the oxygen atom. This arrangement results in a polar bond with the oxygen atom carrying a partial negative charge and the carbon atom a partial positive charge. This polarity can lead to interactions with other polar or charged atoms.

Definition

  1. One atom is a carbonyl oxygen atom (O=C).
  2. The second atom is a carbonyl carbon atom (O=C).
  3. The distance between these two atoms does not exceed a defined distance cutoff.

The directionality of the contact is not considered, meaning that an Oxygen to Carbon contact is equivalent to a Carbon to Oxygen contact.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
distance float

The maximum distance to consider for a carbonyl contact. This value is retrieved

 CONTACTS['carbonyl']['distance']

Returns:

Type Description
NeighborPairs

A NeighborPairs object containing only carbonyl contacts.
Source code in lahuta/contacts/contacts.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def carbonyl_neighbors(ns: NeighborPairs, distance: float = CONTACTS["carbonyl"]["distance"]) -> NeighborPairs:
    """Handle the computation of carbonyl contacts in a molecular system.

    Carbonyl contacts involve the interaction between a carbonyl oxygen atom (O) and a carbonyl carbon atom (C)
    from a carbonyl functional group (C=O) in the context of protein-ligand structures or protein-protein structures.

    In a carbonyl group, the carbon atom has a double bond with the oxygen atom. This arrangement results in a polar
    bond with the oxygen atom carrying a partial negative charge and the carbon atom a partial positive charge.
    This polarity can lead to interactions with other polar or charged atoms.

    !!! tip "Definition"
        1. One atom is a carbonyl oxygen atom (O=C).
        2. The second atom is a carbonyl carbon atom (O=C).
        3. The distance between these two atoms does not exceed a defined distance cutoff.

    The directionality of the contact is not considered, meaning that an Oxygen to Carbon contact is equivalent
    to a Carbon to Oxygen contact.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        distance (float): The maximum distance to consider for a carbonyl contact. This value is retrieved

    Returns:
        (NeighborPairs): A NeighborPairs object containing only carbonyl contacts.
    """
    contacts_atom12 = ns.type_filter("carbonyl_oxygen", 1).type_filter("carbonyl_carbon", 2).distance_filter(distance)

    contacts_atom21 = ns.type_filter("carbonyl_carbon", 1).type_filter("carbonyl_oxygen", 2).distance_filter(distance)

    return contacts_atom12 + contacts_atom21

aromatic_neighbors 

aromatic_neighbors(ns, distance=CONTACTS['aromatic']['distance'])

Handle the computation of aromatic contacts in a molecular structure.

Aromatic contacts are computed based on the interactions between atoms in aromatic rings found in proteins and ligands. Aromatic interactions, commonly found in biological systems, are characterized by π-stacking (face-to-face), T-shaped or edge-to-face configurations, and cation-π interactions.

Definition

  1. Both atoms belong to an aromatic ring.
  2. The distance between these two atoms does not exceed a defined distance cutoff.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
distance float

The maximum distance to consider for contact. Check the default value in lahuta.config.defaults.

 CONTACTS['aromatic']['distance']

Returns:

Type Description
NeighborPairs

A NeighborPairs object containing only aromatic contacts.
Source code in lahuta/contacts/contacts.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
def aromatic_neighbors(ns: NeighborPairs, distance: float = CONTACTS["aromatic"]["distance"]) -> NeighborPairs:
    """Handle the computation of aromatic contacts in a molecular structure.

    Aromatic contacts are computed based on the interactions between atoms in
    aromatic rings found in proteins and ligands. Aromatic interactions,
    commonly found in biological systems, are characterized by π-stacking
    (face-to-face), T-shaped or edge-to-face configurations, and cation-π
    interactions.

    !!! tip "Definition"
        1. Both atoms belong to an aromatic ring.
        2. The distance between these two atoms does not exceed a defined distance cutoff.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        distance (float): The maximum distance to consider for contact. Check the default value in
            `lahuta.config.defaults`.

    Returns:
        (NeighborPairs): A NeighborPairs object containing only aromatic contacts.
    """
    return ns.type_filter("aromatic", 1).type_filter("aromatic", 2).distance_filter(distance)

ionic_neighbors 

ionic_neighbors(ns, distance=CONTACTS['ionic']['distance'])

Handle the computation of ionic contacts in a molecular system.

Ionic contacts refer to the interactions between positively and negatively ionizable atoms, forming one of the primary types of electrostatic interactions.

Definition

  1. One atom must be positively ionizable.
  2. The other atom must be negatively ionizable.
  3. The distance between these two atoms does not exceed a defined distance cutoff.

These criteria apply regardless of the order of the atoms in the pair, meaning a positively ionizable to negatively ionizable contact is considered equivalent to a negatively ionizable to positively ionizable contact.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
distance float

The maximum distance to consider for an ionic contact. This value is retrieved from

 CONTACTS['ionic']['distance']

Returns:

Type Description
NeighborPairs

A NeighborPairs object containing only ionic contacts.
Source code in lahuta/contacts/contacts.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
def ionic_neighbors(ns: NeighborPairs, distance: float = CONTACTS["ionic"]["distance"]) -> NeighborPairs:
    """Handle the computation of ionic contacts in a molecular system.

    Ionic contacts refer to the interactions between positively and negatively ionizable atoms,
    forming one of the primary types of electrostatic interactions.

    !!! tip "Definition"
        1. One atom must be positively ionizable.
        2. The other atom must be negatively ionizable.
        3. The distance between these two atoms does not exceed a defined distance cutoff.

    These criteria apply regardless of the order of the atoms in the pair, meaning a positively ionizable
    to negatively ionizable contact is considered equivalent to a negatively ionizable to positively ionizable contact.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        distance (float): The maximum distance to consider for an ionic contact. This value is retrieved from

    Returns:
        (NeighborPairs): A NeighborPairs object containing only ionic contacts.

    """
    contacts_atom12 = ns.type_filter("pos_ionisable", 1).type_filter("neg_ionisable", 2).distance_filter(distance)

    contacts_atom21 = ns.type_filter("neg_ionisable", 1).type_filter("pos_ionisable", 2).distance_filter(distance)

    return contacts_atom12 + contacts_atom21

hydrophobic_neighbors 

hydrophobic_neighbors(ns, distance=CONTACTS['hydrophobic']['distance'])

Handle the computation of hydrophobic contacts in a molecular system.

Hydrophobic contacts are interactions between hydrophobic atoms in a molecular system. This class, a derivative of the ContactAnalysis base class, overrides the compute method to provide functionality specifically for hydrophobic contact computation.

Hydrophobic contacts are interactions between hydrophobic (non-polar) atoms. Hydrophobic interactions occur due to the tendency of hydrophobic molecules to aggregate together in an aqueous environment, minimizing their exposure to water molecules.

Definition

  1. Both atoms must be hydrophobic.
  2. The distance between these two atoms does not exceed a defined distance cutoff.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
distance float

The maximum distance to consider for a hydrophobic contact.

 CONTACTS['hydrophobic']['distance']

Returns:

Type Description
NeighborPairs

A NeighborPairs object containing only hydrophobic contacts.
Source code in lahuta/contacts/contacts.py 
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
def hydrophobic_neighbors(ns: NeighborPairs, distance: float = CONTACTS["hydrophobic"]["distance"]) -> NeighborPairs:
    """Handle the computation of hydrophobic contacts in a molecular system.

    Hydrophobic contacts are interactions between hydrophobic atoms in a molecular system.
    This class, a derivative of the `ContactAnalysis` base class, overrides the `compute`
    method to provide functionality specifically for hydrophobic contact computation.

    Hydrophobic contacts are interactions between hydrophobic (non-polar) atoms.
    Hydrophobic interactions occur due to the tendency of hydrophobic molecules to aggregate together
    in an aqueous environment, minimizing their exposure to water molecules.

    !!! tip "Definition"
        1. Both atoms must be hydrophobic.
        2. The distance between these two atoms does not exceed a defined distance cutoff.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        distance (float): The maximum distance to consider for a hydrophobic contact.

    Returns:
        (NeighborPairs): A NeighborPairs object containing only hydrophobic contacts.
    """
    return ns.type_filter("hydrophobe", 1).type_filter("hydrophobe", 2).distance_filter(distance)

vdw_neighbors 

vdw_neighbors(ns, vdw_comp_factor=0.1, remove_clashes=True)

Handle the computation of Van der Waals (VdW) contacts in a molecular system.

Van der Waals (VdW) contacts are determined based on the interactions between atoms that come within their combined van der Waals radii, increased by a compensation factor. Van der Waals interactions occur due to induced polarization of atoms and can play a critical role in the stability of biological structures and in molecular recognition processes.

Definition

  1. The distance between two atoms does not exceed the sum of their van der Waals radii, increased by a defined compensation factor.
  2. Optionally, if the distance between two atoms is less than the sum of their van der Waals radii (defined as a clash), the contact can be excluded.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
vdw_comp_factor float

The factor by which Van der Waals radii are multiplied during contact computation. This factor is used in the F.vdw_neighbors function to scale the VdW radii. Default value is 0.1.

 0.1
remove_clashes bool

Flag indicating whether clashes (interactions with distances smaller than the combined Van der Waals radii of two atoms) should be removed. Default value is True.

 True

Returns:

Type Description
NeighborPairs

A NeighborPairs object containing only Van der Waals contacts.
Source code in lahuta/contacts/contacts.py 
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
def vdw_neighbors(ns: NeighborPairs, vdw_comp_factor: float = 0.1, remove_clashes: bool = True) -> NeighborPairs:
    """Handle the computation of Van der Waals (VdW) contacts in a molecular system.

    Van der Waals (VdW) contacts are determined based on the interactions between atoms that come
    within their combined van der Waals radii, increased by a compensation factor.
    Van der Waals interactions occur due to induced polarization of atoms and can play a critical role
    in the stability of biological structures and in molecular recognition processes.

    !!! tip "Definition"
        1. The distance between two atoms does not exceed the sum of their van der Waals radii,
        increased by a defined compensation factor.
        2. Optionally, if the distance between two atoms is less than the sum of their van der Waals radii
        (defined as a clash), the contact can be excluded.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        vdw_comp_factor (float): The factor by which Van der Waals radii are multiplied during contact computation.
            This factor is used in the F.vdw_neighbors function to scale the VdW radii. Default value is 0.1.
        remove_clashes (bool): Flag indicating whether clashes (interactions with distances smaller than
            the combined Van der Waals radii of two atoms) should be removed. Default value is True.

    Returns:
        (NeighborPairs): A NeighborPairs object containing only Van der Waals contacts.
    """
    vdw_radii = ns.atoms.vdw_radii[ns.pairs[:, 0]] + ns.atoms.vdw_radii[ns.pairs[:, 1]]

    distance_mask = ns.distances <= vdw_radii + vdw_comp_factor
    vdw_comp_pairs = ns.pairs[distance_mask]
    vdw_distances = ns.distances[distance_mask]

    if not remove_clashes:
        return ns.clone(vdw_comp_pairs, vdw_distances)  # TODO @bisejdiu: check if this is correct

    vdw_clash_pairs = ns.pairs[ns.distances < vdw_radii]
    no_clash_indices = difference(vdw_comp_pairs, vdw_clash_pairs)

    return ns.clone(vdw_comp_pairs[no_clash_indices], vdw_distances[no_clash_indices])

hbond_neighbors 

hbond_neighbors(ns)

Handle the computation of hydrogen bond (hbond) contacts in a molecular system.

Hydrogen bonds are pivotal non-covalent interactions that significantly influence the structure, stability, and dynamics of biomolecules such as proteins and nucleic acids. A hydrogen bond forms when a hydrogen atom covalently bonded to a highly electronegative atom (such as oxygen or nitrogen) interacts with another electronegative atom from a different group.

Definition

  1. It involves a hydrogen bond donor atom and a hydrogen bond acceptor atom.
  2. The distance between the hydrogen atom and the acceptor atom does not exceed a predefined cutoff distance.
  3. The angle formed by the donor, hydrogen, and acceptor atoms falls within a predefined range. This accounts for the directional nature of hydrogen bonds.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required

Returns:

Type Description
NeighborPairs

A NeighborPairs object containing only hbond contacts.
Source code in lahuta/contacts/contacts.py 
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
def hbond_neighbors(ns: NeighborPairs) -> NeighborPairs:
    """Handle the computation of hydrogen bond (hbond) contacts in a molecular system.

    Hydrogen bonds are pivotal non-covalent interactions that significantly influence the structure, stability,
    and dynamics of biomolecules such as proteins and nucleic acids. A hydrogen bond forms when a hydrogen atom
    covalently bonded to a highly electronegative atom (such as oxygen or nitrogen) interacts with another
    electronegative atom from a different group.

    !!! tip "Definition"
        1. It involves a hydrogen bond donor atom and a hydrogen bond acceptor atom.
        2. The distance between the hydrogen atom and the acceptor atom does not exceed a predefined cutoff distance.
        3. The angle formed by the donor, hydrogen, and acceptor atoms falls within a predefined range.
        This accounts for the directional nature of hydrogen bonds.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.

    Returns:
        (NeighborPairs): A NeighborPairs object containing only hbond contacts.
    """
    hbond_atom12 = (
        ns.type_filter("hbond_donor", 1)
        .type_filter("hbond_acceptor", 2)
        .hbond_distance_filter(partner=2)
        .hbond_angle_filter(partner=1)
    )

    hbond_atom21 = (
        ns.type_filter("hbond_donor", 2)
        .type_filter("hbond_acceptor", 1)
        .hbond_distance_filter(partner=1)
        .hbond_angle_filter(partner=2)
    )

    return hbond_atom12 + hbond_atom21

weak_hbond_neighbors 

weak_hbond_neighbors(ns)

Handle the computation of weak hydrogen bond (weak hbond) contacts in a molecular system.

Weak hydrogen bonds are a type of non-covalent interactions that, despite their reduced strength compared to regular hydrogen bonds, still play important roles in biomolecular structures and functions. These bonds form when a hydrogen atom, covalently linked to a weakly electronegative atom (such as carbon), interacts with an electronegative acceptor atom from a different group. The difference in electronegativity between the donor and acceptor atoms is what makes these bonds relatively weaker than conventional hydrogen bonds.

Definition

  1. A weak hydrogen bond involves a weak hydrogen bond donor atom and a hydrogen bond acceptor atom.
  2. The distance between the hydrogen atom and the acceptor atom does not surpass a certain cutoff distance.
  3. The angle formed by the donor, hydrogen, and acceptor atoms is within a predefined range. This accounts for the directional nature of hydrogen bonds.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required

Returns:

Type Description
NeighborPairs

A NeighborPairs object containing only weak hydrogen bonds.
Source code in lahuta/contacts/contacts.py 
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
def weak_hbond_neighbors(ns: NeighborPairs) -> NeighborPairs:
    """Handle the computation of weak hydrogen bond (weak hbond) contacts in a molecular system.

    Weak hydrogen bonds are a type of non-covalent interactions that, despite their reduced strength
    compared to regular hydrogen bonds, still play important roles in biomolecular structures and functions.
    These bonds form when a hydrogen atom, covalently linked to a weakly electronegative atom (such as carbon),
    interacts with an electronegative acceptor atom from a different group. The difference in electronegativity
    between the donor and acceptor atoms is what makes these bonds relatively weaker than conventional hydrogen bonds.

    !!! tip "Definition"
        1. A weak hydrogen bond involves a weak hydrogen bond donor atom and a hydrogen bond acceptor atom.
        2. The distance between the hydrogen atom and the acceptor atom does not surpass a certain cutoff distance.
        3. The angle formed by the donor, hydrogen, and acceptor atoms is within a predefined range.
        This accounts for the directional nature of hydrogen bonds.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.

    Returns:
        (NeighborPairs): A NeighborPairs object containing only weak hydrogen bonds.
    """
    hbond_atom12 = (
        ns.type_filter("hbond_acceptor", 1)
        .type_filter("weak_hbond_donor", 2)
        .hbond_distance_filter(partner=1)
        .hbond_angle_filter(partner=2, weak=True)
    )

    hbond_atom21 = (
        ns.type_filter("hbond_acceptor", 2)
        .type_filter("weak_hbond_donor", 1)
        .hbond_distance_filter(partner=2)
        .hbond_angle_filter(partner=1, weak=True)
    )

    return hbond_atom12 + hbond_atom21

polar_hbond_neighbors 

polar_hbond_neighbors(ns, distance=CONTACTS['hbond']['polar distance'])

Handle the computation of polar hydrogen bond (polar hbond) contacts in a molecular system.

Polar hydrogen bonds involve a hydrogen atom covalently bonded to a polar atom (hydrogen bond donor), forming an interaction with another polar atom from a different group (hydrogen bond acceptor). In contrast to conventional hydrogen bonds, for polar hydrogen bonds, we do not consider the angle formed by the donor, hydrogen, and acceptor atoms.

Definition

  1. The presence of a hydrogen bond donor and a hydrogen bond acceptor.
  2. The distance between the hydrogen bond donor and the hydrogen bond acceptor does not exceed a specific cutoff distance.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
distance float

The maximum distance to consider for a polar hydrogen bond. Check the default value in lahuta.config.defaults.

 CONTACTS['hbond']['polar distance']

Returns:

Type Description
NeighborPairs

A NeighborPairs object containing only polar hydrogen bonds.
Source code in lahuta/contacts/contacts.py 
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
def polar_hbond_neighbors(ns: NeighborPairs, distance: float = CONTACTS["hbond"]["polar distance"]) -> NeighborPairs:
    """Handle the computation of polar hydrogen bond (polar hbond) contacts in a molecular system.

    Polar hydrogen bonds involve a hydrogen atom covalently bonded to a polar atom (hydrogen bond donor),
    forming an interaction with another polar atom from a different group (hydrogen bond acceptor). In contrast to
    conventional hydrogen bonds, for polar hydrogen bonds, we do not consider the angle formed by the donor, hydrogen,
    and acceptor atoms.

    !!! tip "Definition"
        1. The presence of a hydrogen bond donor and a hydrogen bond acceptor.
        2. The distance between the hydrogen bond donor and the hydrogen bond acceptor does
        not exceed a specific cutoff distance.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        distance (float): The maximum distance to consider for a polar hydrogen bond. Check the default value in
            `lahuta.config.defaults`.

    Returns:
        (NeighborPairs): A NeighborPairs object containing only polar hydrogen bonds.
    """
    hbond_atom12 = ns.type_filter("hbond_donor", 1).type_filter("hbond_acceptor", 2).distance_filter(distance)

    hbond_atom21 = ns.type_filter("hbond_donor", 2).type_filter("hbond_acceptor", 1).distance_filter(distance)

    return hbond_atom12 + hbond_atom21

weak_polar_hbond_neighbors 

weak_polar_hbond_neighbors(ns, distance=CONTACTS['weak hbond']['weak polar distance'])

Handle the computation of weak polar hydrogen bond (weak polar hbond) contacts in a molecular system.

Weak polar hydrogen bonds rely on a weak hydrogen bond donor, and we also do not consider the angle formed by the donor, hydrogen, and acceptor atoms.

Definition

  1. The presence of a hydrogen bond acceptor and a weak hydrogen bond donor.
  2. The distance between the hydrogen bond acceptor and the weak hydrogen bond donor should not exceed a certain cutoff distance.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
distance float

The maximum distance to consider for a weak polar hydrogen bond. Check the default value in lahuta.config.defaults.

 CONTACTS['weak hbond']['weak polar distance']

Returns:

Type Description
NeighborPairs

A NeighborPairs object containing only weak polar hydrogen bonds.ff
Source code in lahuta/contacts/contacts.py 
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
def weak_polar_hbond_neighbors(
    ns: NeighborPairs, distance: float = CONTACTS["weak hbond"]["weak polar distance"]
) -> NeighborPairs:
    """Handle the computation of weak polar hydrogen bond (weak polar hbond) contacts in a molecular system.

    Weak polar hydrogen bonds rely on a weak hydrogen bond donor, and we also do not consider the angle
    formed by the donor, hydrogen, and acceptor atoms.

    !!! tip "Definition"
        1. The presence of a hydrogen bond acceptor and a weak hydrogen bond donor.
        2. The distance between the hydrogen bond acceptor and the weak hydrogen bond donor
        should not exceed a certain cutoff distance.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        distance (float): The maximum distance to consider for a weak polar hydrogen bond. Check the default value in
            `lahuta.config.defaults`.

    Returns:
        (NeighborPairs): A NeighborPairs object containing only weak polar hydrogen bonds.ff
    """
    hbond_atom12 = ns.type_filter("hbond_acceptor", 1).type_filter("weak_hbond_donor", 2).distance_filter(distance)

    hbond_atom21 = ns.type_filter("hbond_acceptor", 2).type_filter("weak_hbond_donor", 1).distance_filter(distance)

    return hbond_atom12 + hbond_atom21

cation_pi 

cation_pi(ns, angle_cutoff=30.0, cache=False)

Handle the computation of cation pi contacts in a molecular system.

Cation pi contacts are interactions between cations and the π system of atoms in a molecule. This class, a derivative of the ContactAnalysis base class, overrides the compute method to provide functionality specifically for cation pi contact computation.

Cation-pi contacts involve interactions between a cation (a positively charged ion) and an electron-rich aromatic ring system. The aromatic system is capable of stabilizing the cation through its delocalized pi electrons.

Definition

  1. The interaction is between an aromatic ring and a positively ionizable atom.
  2. The angle between the aromatic ring plane and the vector connecting the center of the aromatic ring and the cation is within a defined cutoff.
  3. The distance between the cation and the aromatic ring system does not exceed a predefined distance cutoff.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
angle_cutoff float

The maximum angle to consider for a cation pi contact.

 30.0
cache bool

Determines whether computed results should be stored for later use to improve performance.

 False

Returns:

Name Type Description
NeighborPairs NeighborPairs

The computed cation-pi contacts.
Source code in lahuta/contacts/atom_plane.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
def cation_pi(ns: NeighborPairs, angle_cutoff: float = 30.0, cache: bool = False) -> NeighborPairs:
    """Handle the computation of cation pi contacts in a molecular system.

    Cation pi contacts are interactions between cations and the π system of atoms in a molecule.
    This class, a derivative of the `ContactAnalysis` base class, overrides the `compute`
    method to provide functionality specifically for cation pi contact computation.

    Cation-pi contacts involve interactions between a cation (a positively charged ion)
    and an electron-rich aromatic ring system. The aromatic system is capable of stabilizing the cation
    through its delocalized pi electrons.

    !!! tip "Definition"
        1. The interaction is between an aromatic ring and a positively ionizable atom.
        2. The angle between the aromatic ring plane and the vector connecting the center of the aromatic ring
        and the cation is within a defined cutoff.
        3. The distance between the cation and the aromatic ring system does not
        exceed a predefined distance cutoff.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        angle_cutoff (float): The maximum angle to consider for a cation pi contact.
        cache (bool): Determines whether computed results should be stored for later use to improve performance.

    Returns:
        NeighborPairs: The computed cation-pi contacts.

    """
    func = create_contact_function("cation_pi", angle_cutoff, cache)
    return func(ns)

carbon_pi 

carbon_pi(ns, angle_cutoff=30.0, cache=False)

Handle the computation of carbon pi contacts in a molecular system.

Carbon pi contacts are interactions involving the π system of carbon atoms in a molecule. This class, a derivative of the ContactAnalysis base class, overrides the compute method to provide functionality specifically for carbon pi contact computation.

Carbon-pi contacts represent interactions between a carbon atom and an aromatic ring system. These contacts arise due to the partial positive charge on the carbon atom interacting with the electron-rich π-system of the aromatic ring.

Definition

  1. The interaction is between an aromatic ring and a carbon atom which is a weak hydrogen bond donor.
  2. The angle between the aromatic ring plane and the vector connecting the center of the aromatic ring and the carbon atom is within a specified cutoff.
  3. The distance between the carbon atom and the aromatic ring system does not exceed a predefined distance cutoff.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
angle_cutoff float

The maximum angle to consider for a carbon pi contact.

 30.0
cache bool

Determines whether computed results should be stored for later use to improve performance.

 False

Returns:

Name Type Description
NeighborPairs NeighborPairs

The computed carbon-pi contacts.
Source code in lahuta/contacts/atom_plane.py 
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
def carbon_pi(ns: NeighborPairs, angle_cutoff: float = 30.0, cache: bool = False) -> NeighborPairs:
    """Handle the computation of carbon pi contacts in a molecular system.

    Carbon pi contacts are interactions involving the π system of carbon atoms in a molecule.
    This class, a derivative of the `ContactAnalysis` base class, overrides the `compute`
    method to provide functionality specifically for carbon pi contact computation.

    Carbon-pi contacts represent interactions between a carbon atom and an aromatic ring system.
    These contacts arise due to the partial positive charge on the carbon atom interacting with the electron-rich
    π-system of the aromatic ring.

    !!! tip "Definition"
        1. The interaction is between an aromatic ring and a carbon atom which is a weak hydrogen bond donor.
        2. The angle between the aromatic ring plane and the vector connecting the center of the aromatic ring
        and the carbon atom is within a specified cutoff.
        3. The distance between the carbon atom and the aromatic ring system does not
        exceed a predefined distance cutoff.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        angle_cutoff (float): The maximum angle to consider for a carbon pi contact.
        cache (bool): Determines whether computed results should be stored for later use to improve performance.

    Returns:
        NeighborPairs: The computed carbon-pi contacts.

    """
    func = create_contact_function("carbon_pi", angle_cutoff, cache)
    return func(ns)

sulphur_pi 

sulphur_pi(ns, cache=False)

Handle the computation of sulphur pi contacts in a molecular system.

Sulphur pi contacts are interactions involving the π system of sulphur atoms in a molecule. This class, a derivative of the ContactAnalysis base class, overrides the compute method to provide functionality specifically for sulphur pi contact computation.

Sulphur-pi interactions involve the interaction between an aromatic ring and a sulphur atom. Sulphur, particularly from methionine residues (MET), can interact with the electron cloud of an aromatic ring, contributing to the stability and specificity of biomolecular structures.

Definition

  1. The interaction is between an aromatic ring and a sulphur atom specifically in a methionine residue.
  2. The distance between the sulphur atom and the aromatic ring system does not exceed a predefined distance cutoff.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
cache bool

Determines whether computed results should be stored for later use to improve performance.

 False

Returns:

Name Type Description
NeighborPairs NeighborPairs

The computed sulphur-pi contacts.
Source code in lahuta/contacts/atom_plane.py 
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
def sulphur_pi(ns: NeighborPairs, cache: bool = False) -> NeighborPairs:
    """Handle the computation of sulphur pi contacts in a molecular system.

    Sulphur pi contacts are interactions involving the π system of sulphur atoms in a molecule.
    This class, a derivative of the `ContactAnalysis` base class, overrides the `compute`
    method to provide functionality specifically for sulphur pi contact computation.

    Sulphur-pi interactions involve the interaction between an aromatic ring and a sulphur atom.
    Sulphur, particularly from methionine residues (MET), can interact with the electron cloud of an aromatic ring,
    contributing to the stability and specificity of biomolecular structures.

    !!! tip "Definition"
        1. The interaction is between an aromatic ring and a sulphur atom specifically in a methionine residue.
        2. The distance between the sulphur atom and the aromatic ring system
        does not exceed a predefined distance cutoff.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        cache (bool): Determines whether computed results should be stored for later use to improve performance.

    Returns:
        NeighborPairs: The computed sulphur-pi contacts.

    """
    func = create_contact_function("sulphur_pi", None, cache)
    return func(ns)

donor_pi 

donor_pi(ns, angle_cutoff=30.0, cache=False)

Handle the computation of donor pi contacts in a molecular system.

Donor pi contacts are interactions between electron donors and the π system of atoms in a molecule. This class, a derivative of the ContactAnalysis base class, overrides the compute method to provide functionality specifically for donor pi contact computation.

Donor-pi contacts represent interactions between a hydrogen bond donor and an aromatic ring system. The electron-rich aromatic ring can interact with the partial positive charge of a hydrogen atom that is involved in a polar bond, creating a stabilizing interaction.

Definition

  1. The interaction is between an aromatic ring and a hydrogen bond donor.
  2. The angle between the aromatic ring plane and the vector connecting the center of the aromatic ring and the hydrogen bond donor is within a predefined cutoff.
  3. The distance between the hydrogen bond donor and the aromatic ring system does not exceed a specified distance cutoff.

Parameters:

Name Type Description Default
ns NeighborPairs

The object encapsulating pairs of neighboring atoms in the system.

 required
angle_cutoff float

The maximum angle to consider for a donor pi contact.

 30.0
cache bool

Determines whether computed results should be stored for later use to improve performance.

 False

Returns:

Name Type Description
NeighborPairs NeighborPairs

The computed donor-pi contacts.
Source code in lahuta/contacts/atom_plane.py 
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
def donor_pi(ns: NeighborPairs, angle_cutoff: float = 30.0, cache: bool = False) -> NeighborPairs:
    """Handle the computation of donor pi contacts in a molecular system.

    Donor pi contacts are interactions between electron donors and the π system of atoms in a molecule.
    This class, a derivative of the `ContactAnalysis` base class, overrides the `compute`
    method to provide functionality specifically for donor pi contact computation.

    Donor-pi contacts represent interactions between a hydrogen bond donor and an aromatic ring system.
    The electron-rich  aromatic ring can interact with the partial positive charge of a hydrogen atom
    that is involved in a polar bond, creating a stabilizing interaction.

    !!! tip "Definition"
        1. The interaction is between an aromatic ring and a hydrogen bond donor.
        2. The angle between the aromatic ring plane and the vector connecting the center of the aromatic ring
        and the hydrogen bond donor is within a predefined cutoff.
        3. The distance between the hydrogen bond donor and the aromatic ring system
            does not exceed a specified distance cutoff.

    Args:
        ns (NeighborPairs): The object encapsulating pairs of neighboring atoms in the system.
        angle_cutoff (float): The maximum angle to consider for a donor pi contact.
        cache (bool): Determines whether computed results should be stored for later use to improve performance.

    Returns:
        NeighborPairs: The computed donor-pi contacts.

    """
    func = create_contact_function("donor_pi", angle_cutoff, cache)
    return func(ns)

plane_plane_neighbors 

plane_plane_neighbors(ns)

Handle the computation of plane-plane contacts in a molecular system.

This class provides both class and function-level APIs to compute plane-plane contacts between two ring-containing residues or ligands. Each interaction is labeled according to the relative orientations of the planes.

Definitions

FF (Face-Face): Represents two planes interacting in a face-to-face orientation, where their flat surfaces are parallel and directly aligned. This typically leads to maximum pi-pi stacking.

OF (Oblique Face): Denotes a skewed face-to-face orientation. One plane is tilted relative to the other, resulting in partial overlap of their surfaces.

EE (Edge-Edge): Describes an interaction where the edges of two planes align parallel, but their surfaces do not overlap, limiting pi-pi interactions.

FT (Face-T-stack): Indicates an interaction where the face of one plane (the base of the 'T') aligns with the edge of another plane (the stem of the 'T'). The second plane is oriented in a T-stacked manner.

OT (Oblique-T-stack): Represents an interaction where an obliquely oriented face of one plane (the skewed base of the 'T') aligns with the edge of another plane (the stem of the 'T'). The second plane is in a T-stacked orientation.

ET (Edge-T-stack): Describes an interaction where the edge of one plane aligns with the edge of another plane. Both are part of the stem in a T-stacked orientation.

FE (Face-Edge): Depicts an interaction where the flat surface (face) of one plane aligns with the edge of another plane, leading to partial pi-pi interactions.

OE (Oblique-Edge): Represents an interaction where an obliquely oriented face of one plane aligns with the edge of another plane, leading to partial and skewed pi-pi interactions.

EF (Edge-Face): Indicates an interaction where the edge of one plane aligns with the face of another plane, creating limited pi-pi interactions.

Parameters:

Name Type Description Default
ns NeighborPairs

A NeighborPairs object containing the atom neighbor relationships in the system.

 required

Returns:

Name Type Description
NeighborPairs NeighborPairs

A NeighborPairs object containing only plane-plane contacts.
Source code in lahuta/contacts/plane_plane.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
def plane_plane_neighbors(ns: NeighborPairs) -> NeighborPairs:
    """Handle the computation of plane-plane contacts in a molecular system.

    This class provides both class and function-level APIs to compute plane-plane contacts
    between two ring-containing residues or ligands. Each interaction is labeled according
    to the relative orientations of the planes.

    !!! tip "Definitions"
        **FF** _(Face-Face)_: Represents two planes interacting in a face-to-face orientation, where
            their flat surfaces are parallel and directly aligned. This typically leads to
            maximum pi-pi stacking.

        **OF** _(Oblique Face)_: Denotes a skewed face-to-face orientation. One plane is tilted
            relative to the other, resulting in partial overlap of their surfaces.

        **EE** _(Edge-Edge)_: Describes an interaction where the edges of two planes align parallel,
            but their surfaces do not overlap, limiting pi-pi interactions.

        **FT** _(Face-T-stack)_: Indicates an interaction where the face of one plane (the base of the 'T')
            aligns with the edge of another plane (the stem of the 'T'). The second plane is
            oriented in a T-stacked manner.

        **OT** _(Oblique-T-stack)_: Represents an interaction where an obliquely oriented face of one
            plane (the skewed base of the 'T') aligns with the edge of another plane (the stem of
            the 'T'). The second plane is in a T-stacked orientation.

        **ET** _(Edge-T-stack)_: Describes an interaction where the edge of one plane aligns with the
            edge of another plane. Both are part of the stem in a T-stacked orientation.

        **FE** _(Face-Edge)_: Depicts an interaction where the flat surface (face) of one plane aligns
            with the edge of another plane, leading to partial pi-pi interactions.

        **OE** _(Oblique-Edge)_: Represents an interaction where an obliquely oriented face of one plane
            aligns with the edge of another plane, leading to partial and skewed pi-pi interactions.

        **EF** _(Edge-Face)_: Indicates an interaction where the edge of one plane aligns with the face of
            another plane, creating limited pi-pi interactions.

    Args:
        ns (NeighborPairs): A NeighborPairs object containing the atom neighbor relationships in the system.

    Returns:
        NeighborPairs: A NeighborPairs object containing only plane-plane contacts.

    """
    plane_plane = _PlanePlaneContacts(ns)
    plane_plane.compute()
    return plane_plane.get_neighbors()