Interaction API

Introduction

InteractionLibrary is a knowledge-based library of intermolecular interactions.

The ccdc.interaction module gives access to the InteractionLibrary central and contact groups. It also provides an interface for working with the data stored in .istr files.

>>> 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 MoleculeReader
>>> csd_molecule_reader = MoleculeReader('CSD')
>>> aabhtz = csd_molecule_reader.molecule('AABHTZ')
>>> aabhtz_central_group_hits = central_lib.search_molecule(aabhtz)
>>> 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)]

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.

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.

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.

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.