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.91, 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(10.0 * len(near_obs) / len(hb.observations)) * 10
...     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 80% observed hydrogen bonds near

See also

Descriptive Interaction Library documentation.

See also

Descriptive Hydrogen Bond Statistics documentation.

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_group – ccdc.interaction.InteractionLibrary.ContactGroup

Returns:

ccdc.interaction.InteractionLibrary.InteractionData

property 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:

central – ccdc.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().

property name

The name of the group matched the hit.

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

Class for working with interaction data.

property average_density

Average density of the data.

property central_group_name

Name of the central group.

property contact_group_name

Name of the contact group.

property histogram

Histogram of contact distances.

property hits

The entry hits in this file.

property max_distance

Furthest distance in the histogram.

property min_distance

Closest distance in the histogram.

property ncentral_atoms

Number of atoms in the central group.

property ncontact_atoms

Number of atoms in the contact group.

property ncontacts

Number of observations in the istr file.

ncontacts_in_range(low, high)[source]

The number of observations in a given distance range

property nflexible_atoms

Number of flexible atoms.

property nvdw_contacts

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

property 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

property crystal

The crystal of the hit

property distance

Distance between central and contact groups relative to Sum VdW

property entry

The entry for the hit

property identifier

The refcode of the hit

property 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

property custom_grid_bounding_box

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

property detect_hotspots

Whether or not to detect hotspots in the grids.

property grid_spacing

The grid spacing to be used for the analysis.

property hotspots_min_value

The minimum value at which a hotspot will be detected.

property hotspots_ncycles

The number of cycles of hotspot fitting to perform.

property hotspots_refine

Whether or not to refine the hotspots calculation.

property 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.

property 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’]

property apolar_shell_correction

The apolar shell correction parameter.

property calculate_connolly_surface

Whether or not to calculate a Connolly surface.

property calculate_contour_surface

Whether or not to calculate a countour surface.

property cavity_origin

The origin of the cavity if set, otherwise None.

property cavity_radius

The radius of the cavity when searching from an origin.

property detect_cavities

Whether or not to detect the cavities of the protein.

property 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.

property logp_hydrophobic_attenuation_a

LogP attenuation a factor.

property logp_hydrophobic_attenuation_b

LogP attenuation factor b.

property 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.

property min_cavity_volume

The minimum volume required for a cavity.

property polar_shell_correction

The polar shell correction parameter.

property rotate_torsions

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

property 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.

property 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.

property acceptor_atom

Return the observed hydrogen bond acceptor atom.

property angle

The donor-acceptor angle in the hydrogen bond observation.

property distance

The donor-acceptor distance in the hydrogen bond observation.

property donor_atom

Return the observed hydrogen bond donor atom.

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

Information about a hydrogen bond

property acceptor_atom

The acceptor atom from the query crystal.

property acceptor_functional_group_name

The acceptor functional group name.

property angle

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

property angle_histogram_effective_densities

Effective Densities of bins for angle histograms

property angle_histogram_frequencies

Frequency counts of bins in angle histogram

property angle_histogram_weights

Weights of bins in angle histograms

property angle_histogram_x_axis_properties

X-axis properties of angle histogram, :returns: a tuple containing the various x-axis properties needed to plot an angle histogram :rtype::tuple: - (start, stop, number of bins)

property angle_max

The maximum angle of contacts in the query.

property angle_mean

The mean angle in the query.

property angle_min

The minimum angle of contacts in the query.

property angle_stdev

The standard deviation of angle of contacts in the query.

property angle_threshold

The value of the threshold angle in the query.

property angle_unusual

Whether the angle falls below the usual angle quantile limit.

property angles

The observed angle measurements with invalid angles filtered out.

property distance

The donor-acceptor distance in the query.

property distance_histogram_effective_densities

Effective Densities of bins for distance histograms

property distance_histogram_frequencies

Frequency counts of bins in distance histogram

property distance_histogram_weights

Weights of bins in distance histograms

property distance_histogram_x_axis_properties

X-axis properties of distance histogram, :returns: a tuple containing the various x-axis properties needed to plot a distance histogram :rtype::tuple: - (start, stop, number of bins)

property distance_max

The maximum angle of contacts in the query.

property distance_mean

The mean distance in the query.

property distance_min

The minimum angle of contacts in the query.

property distance_stdev

The standard deviation of angle of contacts in the query.

property distance_threshold

The value of the threshold distances in the query

property distance_unusual

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

property distances

The observed distance measurements.

property donor_atom

The donor atom from the query crystal.

property donor_functional_group_name

The donor functional group name.

property heatplot_angles_cone_corrected

Returns the cone corrected angle data for plotting heatplots

property heatplot_distances_radial_corrected

Returns the radial corrected distance data for plotting heatplots

property intermolecular

True if the hydrogen bond is intermolecular, false otherwise.

property observations

The observations of this hydrogen bond found in the database.

class Settings[source]

Settings for a hydrogen bond statistics search.

Attributes

max_distancefloat

this is the maximum VDW-adjusted donor-acceptor contact distance limit.

min_anglefloat

this is the minimum accepted donor-hydrogen-acceptor angle limit (in degrees). This will be ignored if require_hydrogen is False.

require_hydrogenbool

whether or not the donor is required to have a hydrogen atom with defined coordinates.

usual_distance_lower_quantilefloat

the lower quantile limit for unusual distances.

usual_distance_upper_quantilefloat

the upper quantile limit for unusual distances.

usual_angle_lower_quantilefloat

the lower quantile limit for unusual angles.

search(crystal, database=None)[source]

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