Interaction API

Introduction

The ccdc.interaction module contains classes for investigating molecular interaction statistics. The InteractionLibrary is a knowledge-based library of intermolecular interactions. This module gives access to the InteractionLibrary central and contact groups. It also provides an interface for working with the data stored in .istr files. It also provides hydrogren bond statistics search classes.

>>> from ccdc.interaction import InteractionLibrary
>>> central_lib = InteractionLibrary.CentralGroupLibrary()
>>> contact_lib = InteractionLibrary.ContactGroupLibrary()
>>> central_ketone = central_lib.group_by_name('aliphatic-aliphatic ketone')
>>> contact_alcohol = contact_lib.group_by_name('alcohol OH')
>>> interaction_data = central_ketone.interaction_data(contact_alcohol)
>>> print('Rel. density %.2f, est. std.dev. %.2f' % interaction_data.relative_density)
Rel. density 2.88, est. std.dev. 0.23

Methods to establish which central and contact groups are present in a molecule are provided.

>>> from ccdc.io import CrystalReader
>>> csd_crystal_reader = CrystalReader('CSD')
>>> aabhtz = csd_crystal_reader.crystal('AABHTZ')
>>> aabhtz_central_group_hits = central_lib.search_molecule(aabhtz.molecule)
>>> len(aabhtz_central_group_hits)
4

The order of the central group hits is indeterminate. However, we do know that methyl is present in AABHTZ.

>>> names = [g.name for g in aabhtz_central_group_hits]
>>> assert('methyl' in names)
>>> i = names.index('methyl')
>>> print(aabhtz_central_group_hits[i].match_atoms())
[Atom(C10), Atom(C11), Atom(H7), Atom(H8), Atom(H9)]

Hydrogen bond statistics can be investigated with HydrogenBondStatisticsSearch.

>>> from ccdc.interaction import HydrogenBondStatisticsSearch
>>> hbs = HydrogenBondStatisticsSearch()
>>> stats = hbs.search(aabhtz)
>>> for hb in stats:
...     near_obs = [ob for ob in hb.observations if hb.distance-0.1 < ob.distance < hb.distance+0.1]
...     near_percent = round(100.0 * len(near_obs) / len(hb.observations))
...     classification = "unusual" if hb.distance_unusual else "normal"
...     print(f'{hb.donor_atom.label}-{hb.acceptor_atom.label} has {classification} distance with {near_percent}% observed hydrogen bonds near')
N6-O2 has normal distance with 78% observed hydrogen bonds near

API

class ccdc.interaction.InteractionLibrary[source]

The InteractionLibrary derived from CSD data.

class CentralGroup(_group)[source]

central group definition.

contact_groups()[source]

Return list of contact groups for which the interaction library has data.

The ccdc.interaction.InteractionLibrary.ContactGroup instances returned are the ones for which the specific ccdc.interaction.InteractionLibrary.CentralGroup has data.

Returns:list of ccdc.interaction.InteractionLibrary.ContactGroup instances
interaction_data(contact_group)[source]

Return the file for this central group and the contact group.

Parameters:contact_groupccdc.interaction.InteractionLibrary.ContactGroup
Returns:ccdc.interaction.InteractionLibrary.InteractionData
name

The name of the group.

class CentralGroupLibrary[source]

Collection of central groups.

groups list of ccdc.interaction.InteractionLibrary.CentralGroup instances in the library

class ContactGroup(_group)[source]

contact group definition

central_groups()[source]

List of central groups which have data for this contact group

Returns:list of ccdc.interaction.InteractionLibrary.CentralGroup instances
interaction_data(central)[source]

The ccdc.interaction.InteractionLibrary.InteractionData corresponding to the given central group and this contact group

Parameters:centralccdc.interaction.InteractionLibrary.CentralGroup
class ContactGroupLibrary[source]

Collection of contact groups.

groups list of ccdc.interaction.InteractionLibrary.ContactGroup instances in the library

group_by_index(index)[source]

Find a contact group by index.

Parameters:index – integer index of the group to return
Returns:the ccdc.interaction.InteractionLibrary.ContactGroup
class FunctionalGroupHit(group, hit)[source]

A hit from a functional group search.

match_atoms(indices=False)[source]

Returns the matched atoms. See ccdc.search.SubstructureHit.match_atoms().

name

The name of the group matched the hit.

class InteractionData(fname=None, _istr_data=None)[source]

Class for working with interaction data.

average_density

Average density of the data.

central_group_name

Name of the central group.

contact_group_name

Name of the contact group.

histogram

Histogram of contact distances.

hits

The entry hits in this file.

max_distance

Furthest distance in the histogram.

min_distance

Closest distance in the histogram.

ncentral_atoms

Number of atoms in the central group.

ncontact_atoms

Number of atoms in the contact group.

ncontacts

Number of observations in the istr file.

ncontacts_in_range(low, high)[source]

The number of observations in a given distance range

nflexible_atoms

Number of flexible atoms.

nvdw_contacts

Number of observations with a distance <= sum of VdW radii.

relative_density

Relative density and estimated standard deviation tuple.

write(file_name)[source]

Writes the data to file.

class InteractionHit(_link)[source]

A hit from InteractionData

central_group_atoms(indices=False)[source]

The atoms of the central group

contact_group_atoms(indices=False)[source]

The atoms of the contact group

crystal

The crystal of the hit

distance

Distance between central and contact groups relative to Sum VdW

entry

The entry for the hit

identifier

The refcode of the hit

molecule

The molecule of the hit

class ccdc.interaction.InteractionMapAnalysis(settings=None)[source]

Searches crystals for potential interactions.

class CommonSettings(_settings=None)[source]

Settings common to protein and small molecule analyses.

Variables:
  • working_directory – default value ‘./’
  • probe_names – default value [‘Uncharged NH Nitrogen’, ‘Carbonyl Oxygen’, ‘Aromatic CH Carbon’]
csd_defined_probes = ['Uncharged NH Nitrogen', 'Charged NH Nitrogen', 'RNH3 Nitrogen', 'Alcohol Oxygen', 'Carbonyl Oxygen', 'Water Oxygen', 'Oxygen Atom', 'Methyl Carbon', 'Aromatic CH Carbon', 'C-F Fluorine', 'C-Cl Chlorine', 'C-Br Bromine', 'C-I Iodine', 'Sp2 CNC Nitrogen', 'Carboxylate Oxygen', 'Nitro Oxygen', 'Chloride Anion']

Defined probes using CSD data

custom_grid_bounding_box

The custom grid if it has been set, or None.

detect_hotspots

Whether or not to detect hotspots in the grids.

grid_spacing

The grid spacing to be used for the analysis.

hotspots_min_value

The minimum value at which a hotspot will be detected.

hotspots_ncycles

The number of cycles of hotspot fitting to perform.

hotspots_refine

Whether or not to refine the hotspots calculation.

num_threads

Number of threads to use, default -1 (all but one).

set_custom_grid_from_grid(grid)[source]

A convenience to set spacing and bounding box.

summary()[source]

Prints a table of settings.

working_directory

The parent directory of all result directories.

write(file_name)[source]

Write the settings to an INS file.

class ProteinSettings(_settings=None)[source]

Settings pertaining to protein analysis.

Variables:
  • working_directory – default value ‘./’
  • probe_names – default value [‘Uncharged NH Nitrogen’, ‘Carbonyl Oxygen’, ‘Aromatic CH Carbon’]
apolar_shell_correction

The apolar shell correction parameter.

calculate_connolly_surface

Whether or not to calculate a Connolly surface.

calculate_contour_surface

Whether or not to calculate a countour surface.

cavity_origin

The origin of the cavity if set, otherwise None.

cavity_radius

The radius of the cavity when searching from an origin.

detect_cavities

Whether or not to detect the cavities of the protein.

detect_cavity_from_residues

List of residues from which cavities will be detected.

static from_file(file_name)[source]

Reads ProteinSettings from an INS file.

logp_hydrophobic_attenuation_a

LogP attenuation a factor.

logp_hydrophobic_attenuation_b

LogP attenuation factor b.

min_cavity_buriedness

Threshold for the detection of buried cavities.

One of ‘shallow’, ‘shallow/normal’, ‘normal’, ‘normal/buried’, ‘buried’. When assigning one these values may be specified, or a value between 1 and 7, the higher the value the more buried a cavity must be in order to be detected.

min_cavity_volume

The minimum volume required for a cavity.

polar_shell_correction

The polar shell correction parameter.

rotate_torsions

Whether or not to rotate R-[O,N,S]-H bonds.

source

The source for scatterplot data.

One of ‘CSD’, ‘CSD_SMALL’, ‘PDB’.

summary()[source]

A summary of current settings.

write(file_name)[source]

Write the settings.

class Results(output_directory, settings=None)[source]

The results of a InteractionMapAnalysis analysis.

Previous results may be processed by instantiating this class with a directory.

The grids generated by the InteractionMapAnalysis are presented as dictionary-like attributes of this class, keyed by the probe name.

class Hotspot(coordinates, value)
coordinates

Alias for field number 0

value

Alias for field number 1

error_file(probe_name)[source]

Read and return the error file for a probe.

hotspots(probe_name)[source]

Return the hotspots for the given probe.

log_file(probe_name)[source]

Read and return the log file for a probe.

class SmallMoleculeSettings(_settings=None)[source]

Settings pertaining to small molecule analysis.

Variables:
  • working_directory – default value ‘./’
  • probe_names – default value [‘Uncharged NH Nitrogen’, ‘Carbonyl Oxygen’, ‘Aromatic CH Carbon’]
static from_file(file_name)[source]

Reads SmallMoleculeSettings from an INS file.

summary()[source]

A summary of current settings.

class SurfaceSettings(_settings=None)[source]

Settings pertaining to surface analysis.

Variables:
  • working_directory – default value ‘./’
  • probe_names – default value [‘Uncharged NH Nitrogen’, ‘Carbonyl Oxygen’, ‘Aromatic CH Carbon’]
static from_file(file_name)[source]

Reads SurfaceSettings from an INS file.

grid_spacing

The grid spacing to be used for the analysis.

analyse_ligand(protein, ligand, prepared=False)[source]

Analyses a ligand in the protein.

Parameters:
Returns:

a ccdc.interaction.InteractionMapAnalysis.Results instance.

analyse_protein(protein, prepared=False)[source]

Analyses the given protein.

Parameters:
  • protein – a ccdc.protein.Protein instance.
  • prepared – if True then no preparation of the protein will be done; if False, ligands and waters will be removed, and hydrogens added.
Returns:

a ccdc.interaction.InteractionMapAnalysis.Results instance.

analyse_small_molecule(molecule)[source]

Analyses the given crystal.

Parameters:molecule – a ccdc.molecule.Molecule instance.
Returns:a ccdc.interaction.InteractionMapAnalysis.Results instance.

If molecules are provided, the analysis they should be a collection of molecules derived from the crystal.

All saved files will be in a subdirectory, ccdc.crystal.Crystal.identifier, of ccdc.interaction.InteractionMapAnalysis.Settings.working_directory.

analyse_surface(surface)[source]

Analyses the given surface.

Parameters:surface – a ccdc.particle.Surface instance.
Returns:a ccdc.interaction.InteractionMapAnalysis.Results instance.

All saved files will be in a subdirectory, ccdc.particle.Surface.identifier, of ccdc.interaction.InteractionMapAnalysis.Settings.working_directory.

cavities(protein, prepared=False)[source]

Detects the cavities of the protein.

Parameters:
  • protein – a ccdc.protein.Protein instance.
  • prepared – if True, no protein preparation will be performed; if False ligands and waters will be removed and hydrogens added.
Returns:

ccdc.interaction.InteractionMapAnalysis.Results class.

class ccdc.interaction.HydrogenBondStatisticsSearch(settings=None)[source]

Generate statistics about hydrogen bond interactions within crystals.

class HydrogenBondObservation(obs, database)[source]

A hydrogen bond observation.

acceptor_atom

Return the observed hydrogen bond acceptor atom.

angle

The donor-acceptor angle in the hydrogen bond observation.

distance

The donor-acceptor distance in the hydrogen bond observation.

donor_atom

Return the observed hydrogen bond donor atom.

class HydrogenBondStatistics(stats, crystal, database, settings)[source]

Information about a hydrogen bond

acceptor_atom

The acceptor atom from the query crystal.

acceptor_functional_group_name

The acceptor functional group name.

angle

The donor-hydrogen-acceptor angle in the query, which may be NaN.

angle_unusual

Whether the angle falls below the usual angle quantile limit.

angles

The observed angle measurements with invalid angles filtered out.

distance

The donor-acceptor distance in the query.

distance_unusual

Whether the distance falls outside of the usual distance quantile range.

distances

The observed distance measurements.

donor_atom

The donor atom from the query crystal.

donor_functional_group_name

The donor functional group name.

intermolecular

True if the hydrogen bond is intermolecular, false otherwise.

observations

The observations of this hydrogen bond found in the database.

class Settings[source]

Settings for a hydrogen bond statistics search.

max_distance : float
this is the maximum VDW-adjusted donor-acceptor contact distance limit.
min_angle : float
this is the minimum accepted donor-hydrogen-acceptor angle limit (in degrees). This will be ignored if require_hydrogen is False.
require_hydrogen : bool
whether or not the donor is required to have a hydrogen atom with defined coordinates.
usual_distance_lower_quantile : float
the lower quantile limit for unusual distances.
usual_distance_upper_quantile : float
the upper quantile limit for unusual distances.
usual_angle_lower_quantile : float
the lower quantile limit for unusual angles.
search(crystal, database=None)[source]

Return hydrogen bond statistics relevant to a crystal structure, from a database.