Interaction API


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. %.2f' % interaction_data.relative_density)
Rel. density 2.88, est. 0.23

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

>>> from 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)

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

>>> names = [ 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 =
>>> 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


class ccdc.interaction.InteractionLibrary[source]

The InteractionLibrary derived from CSD data.

class CentralGroup(_group)[source]

central group definition.


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.


list of ccdc.interaction.InteractionLibrary.ContactGroup instances


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





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


List of central groups which have data for this contact group


list of ccdc.interaction.InteractionLibrary.CentralGroup instances


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



class ContactGroupLibrary[source]

Collection of contact groups.

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


Find a contact group by index.


index – integer index of the group to return


the ccdc.interaction.InteractionLibrary.ContactGroup

class FunctionalGroupHit(group, hit)[source]

A hit from a functional group search.


Returns the matched atoms. See

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.


Writes the data to file.

class InteractionHit(_link)[source]

A hit from InteractionData


The atoms of the central group


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.

  • 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).


A convenience to set spacing and bounding box.


Prints a table of settings.

property working_directory

The parent directory of all result directories.


Write the settings to an INS file.

class ProteinSettings(_settings=None)[source]

Settings pertaining to protein analysis.

  • 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’.


A summary of current settings.


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)
property coordinates

Alias for field number 0

property value

Alias for field number 1


Read and return the error file for a probe.


Return the hotspots for the given probe.


Read and return the log file for a probe.

class SmallMoleculeSettings(_settings=None)[source]

Settings pertaining to small molecule analysis.

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


A summary of current settings.

class SurfaceSettings(_settings=None)[source]

Settings pertaining to surface analysis.

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


a ccdc.interaction.InteractionMapAnalysis.Results instance.

analyse_protein(protein, prepared=False)[source]

Analyses the given protein.

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


a ccdc.interaction.InteractionMapAnalysis.Results instance.


Analyses the given crystal.


molecule – a ccdc.molecule.Molecule instance.


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.


Analyses the given surface.


surface – a ccdc.particle.Surface instance.


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.

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


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



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


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


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


the lower quantile limit for unusual distances.


the upper quantile limit for unusual distances.


the lower quantile limit for unusual angles.

search(crystal, database=None)[source]

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