The ihm.restraint Python module

Classes for handling restraints on the system.

class ihm.restraint.PseudoSite(x, y, z, radius=None, description=None)[source]

Selection of a pseudo position in the system. Pseudo positions are typically used to reference a point or sphere that is not explcitly represented, in a PseudoSiteFeature or CrossLinkPseudoSite.

Parameters:

  • x (float) – Cartesian X coordinate of this site.

  • y (float) – Cartesian Y coordinate of this site.

  • z (float) – Cartesian Z coordinate of this site.

  • radius (float) – Radius of the site, if applicable.

  • description (str) – Additional text describing this feature.

class ihm.restraint.Restraint[source]

Base class for all restraints. See ihm.System.restraints.

class ihm.restraint.RestraintGroup(iterable=(), /)[source]

A set of related Restraint objects. This is implemented as a simple list.

Note that due to limitations of the underlying dictionary, only certain combinations of restraints can be placed in groups. In particular, all objects in a group must be of the same type, and only certain types (currently only DerivedDistanceRestraint and PredictedContactRestraint) can be grouped.

Empty groups can be created, but will be ignored on output as the dictionary does not support them.

Restraint groups should be stored in the system by adding them to ihm.System.restraint_groups.

class ihm.restraint.EM3DRestraint(dataset, assembly, segment=None, fitting_method=None, fitting_method_citation=None, number_of_gaussians=None, details=None)[source]

Restrain part of the system to match an electron microscopy density map.

Parameters:

  • dataset (Dataset) – Reference to the density map data (usually an EMDensityDataset).

  • assembly (Assembly) – The part of the system that is fit into the map.

  • segment (bool) – True iff the map has been segmented.

  • fitting_method (str) – The method used to fit the model into the map.

  • fitting_method_citation (Citation) – The publication describing the fitting method.

  • number_of_gaussians (int) – Number of Gaussians used to represent the map as a Gaussian Mixture Model (GMM), if applicable.

  • details (str) – Additional details regarding the fitting.

fits

Information about the fit of each model to this restraint’s data. This is a Python dict where keys are Model objects and values are EM3DRestraintFit objects.

class ihm.restraint.EM3DRestraintFit(cross_correlation_coefficient=None)[source]

Information on the fit of a model to an EM3DRestraint. See EM3DRestaint.fits.

Parameters:

cross_correlation_coefficient (float) – The fit between the model and the map.

class ihm.restraint.EM2DRestraint(dataset, assembly, segment=None, number_raw_micrographs=None, pixel_size_width=None, pixel_size_height=None, image_resolution=None, number_of_projections=None, details=None)[source]

Restrain part of the system to match an electron microscopy class average.

Parameters:

  • dataset (Dataset) – Reference to the class average data (usually an EM2DClassDataset).

  • assembly (Assembly) – The part of the system that is fit against the class.

  • segment (bool) – True iff the image has been segmented.

  • number_raw_micrographs (int) – The number of particles picked from the original raw micrographs that were used to create the class average.

  • pixel_size_width (float) – Width of each pixel in the image, in angstroms.

  • pixel_size_height (float) – Height of each pixel in the image, in angstroms.

  • image_resolution (float) – Resolution of the image, in angstroms.

  • number_of_projections (int) – Number of projections of the assembly used to fit against the image, if applicable.

  • details (str) – Additional details regarding the fitting.

fits

Information about the fit of each model to this restraint’s data. This is a Python dict where keys are Model objects and values are EM2DRestraintFit objects.

class ihm.restraint.EM2DRestraintFit(cross_correlation_coefficient=None, rot_matrix=None, tr_vector=None)[source]

Information on the fit of a model to an EM2DRestraint. See EM2DRestaint.fits.

Parameters:

  • cross_correlation_coefficient (float) – The fit between the model and the class average.

  • rot_matrix – Rotation matrix (as a 3x3 array of floats) that places the model on the image.

  • tr_vector – Translation vector (as a 3-element float list) that places the model on the image.

class ihm.restraint.SASRestraint(dataset, assembly, segment=None, fitting_method=None, fitting_atom_type=None, multi_state=None, radius_of_gyration=None, details=None)[source]

Restrain part of the system to match small angle scattering (SAS) data.

Parameters:

  • dataset (Dataset) – Reference to the SAS data (usually an SASDataset).

  • assembly (Assembly) – The part of the system that is fit against SAS data.

  • segment (bool) – True iff the SAS profile has been segmented.

  • fitting_method (str) – The method used to fit the model against the SAS data (e.g. FoXS, DAMMIF).

  • fitting_atom_type (str) – The set of atoms fit against the data (e.g. “Heavy atoms”, “All atoms”).

  • multi_state (bool) – Whether multiple state fitting was done.

  • radius_of_gyration (float) – Radius of gyration obtained from the SAS profile, if used as part of the restraint.

  • details (str) – Additional details regarding the fitting.

fits

Information about the fit of each model to this restraint’s data. This is a Python dict where keys are Model objects and values are SASRestraintFit objects.

class ihm.restraint.SASRestraintFit(chi_value=None)[source]

Information on the fit of a model to a SASRestraint. See SASRestaint.fits.

Parameters:

chi_value (float) – The fit between the model and the SAS data.

class ihm.restraint.DistanceRestraint[source]

Base class for all distance restraints. These are typically used in a DerivedDistanceRestraint.

Do not use this class directly but instead use a derived class such as HarmonicDistanceRestraint, UpperBoundDistanceRestraint, LowerBoundDistanceRestraint, or LowerUpperBoundDistanceRestraint.

distance_lower_limit = None

The minimum distance allowed for this restraint, or None if unconstrained

distance_upper_limit = None

The maximum distance allowed for this restraint, or None if unconstrained

class ihm.restraint.HarmonicDistanceRestraint(distance)[source]

Harmonically restrain two objects to be close to a given distance apart. These objects are typically used in a DerivedDistanceRestraint.

Parameters:

distance (float) – Equilibrium distance

property distance_lower_limit

The equilibrium distance

property distance_upper_limit

The equilibrium distance

class ihm.restraint.UpperBoundDistanceRestraint(distance)[source]

Harmonically restrain two objects to be below a given distance apart. These objects are typically used in a DerivedDistanceRestraint.

Parameters:

distance (float) – Distance threshold

distance_lower_limit = None

Minimum distance (unconstrained, so always None)

property distance_upper_limit

The maximum distance allowed by this restraint

class ihm.restraint.LowerBoundDistanceRestraint(distance)[source]

Harmonically restrain two objects to be above a given distance apart. These objects are typically used in a DerivedDistanceRestraint.

Parameters:

distance (float) – Distance threshold

property distance_lower_limit

The minimum distance allowed by this restraint

distance_upper_limit = None

Maximum distance (unconstrained, so always None)

class ihm.restraint.LowerUpperBoundDistanceRestraint(distance_lower_limit, distance_upper_limit)[source]

Harmonically restrain two objects to be above a given distance and below another distance apart. These objects are typically used in a DerivedDistanceRestraint.

Parameters:

  • distance_lower_limit (float) – Lower bound on the distance.

  • distance_upper_limit (float) – Upper bound on the distance.

class ihm.restraint.CrossLinkRestraint(dataset, linker)[source]

Restrain part of the system to match a set of cross-links.

Parameters:

All cross-links used in the modeling, as a list of CrossLink objects.

All cross-links identified in the experiment, as a simple list of lists of ExperimentalCrossLink objects. All cross-links in the same sublist are treated as experimentally ambiguous. For example, xl2 and xl3 here are considered ambiguous:

restraint.experimental_cross_links.append([xl1])
restraint.experimental_cross_links.append([xl2, xl3])

A cross-link identified in the experiment.

These objects, once created, should be added to the CrossLinkRestraint.experimental_cross_links list.

Parameters:

  • residue1 (ihm.Residue) – The first residue linked by the cross-link.

  • residue2 (ihm.Residue) – The second residue linked by the cross-link.

  • details (str) – Additional text describing the cross-link.

class ihm.restraint.CrossLinkPseudoSite(site, model=None)[source]

Pseudo site corresponding to one end of a cross-link.

These objects are used when the end of a cross-link is not represented in the model but its position is known (e.g. it may have been approximated given the position of nearby residues). They are passed as the pseudo1 or pseudo2 arguments to CrossLink subclasses.

Parameters:

  • site (PseudoSite) – The pseudo site coordinates

  • model (ihm.model.Model) – The model in whose coordinate system the pseudo site is active (if not specified, the coordinates are assumed to be valid for all models using this cross-link).

Base class for all cross-links used in the modeling. Do not use this class directly, but instead use a subclass: ResidueCrossLink, AtomCrossLink, or FeatureCrossLink.

A cross-link used in the modeling, applied to residue alpha carbon atoms.

These objects, once created, should be added to the CrossLinkRestraint.cross_links list.

Parameters:

  • experimental_cross_link (ExperimentalCrossLink) – The corresponding cross-link identified by experiment. Multiple cross-links can map to a single experimental identification.

  • asym1 (ihm.AsymUnit) – The asymmetric unit containing the first linked residue.

  • asym2 (ihm.AsymUnit) – The asymmetric unit containing the second linked residue.

  • distance (DistanceRestraint) – Restraint on the distance.

  • psi (float) – Initial uncertainty in the experimental data.

  • sigma1 (float) – Initial uncertainty in the position of the first residue.

  • sigma2 (float) – Initial uncertainty in the position of the second residue.

  • restrain_all (bool) – If True, all cross-links are restrained.

  • pseudo1 (List of CrossLinkPseudoSite) – List of pseudo sites representing the position of the first residue (if applicable).

  • pseudo2 (List of CrossLinkPseudoSite) – List of pseudo sites representing the position of the second residue (if applicable).

fits

Information about the fit of each model to this cross-link. This is a Python dict where keys are Model objects and values are CrossLinkFit objects.

property residue1

Residue object representing one end of the cross-link

property residue2

Residue object representing one end of the cross-link

A cross-link used in the modeling, applied to the closest primitive object with the highest resolution.

These objects, once created, should be added to the CrossLinkRestraint.cross_links list.

Parameters:

  • experimental_cross_link (ExperimentalCrossLink) – The corresponding cross-link identified by experiment. Multiple cross-links can map to a single experimental identification.

  • asym1 (ihm.AsymUnit) – The asymmetric unit containing the first linked residue.

  • asym2 (ihm.AsymUnit) – The asymmetric unit containing the second linked residue.

  • distance (DistanceRestraint) – Restraint on the distance.

  • psi (float) – Initial uncertainty in the experimental data.

  • sigma1 (float) – Initial uncertainty in the position of the first residue.

  • sigma2 (float) – Initial uncertainty in the position of the second residue.

  • restrain_all (bool) – If True, all cross-links are restrained.

  • pseudo1 (List of CrossLinkPseudoSite) – List of pseudo sites representing the position of the first residue (if applicable).

  • pseudo2 (List of CrossLinkPseudoSite) – List of pseudo sites representing the position of the second residue (if applicable).

fits

Information about the fit of each model to this cross-link. This is a Python dict where keys are Model objects and values are CrossLinkFit objects.

A cross-link used in the modeling, applied to the specified atoms.

These objects, once created, should be added to the CrossLinkRestraint.cross_links list.

Parameters:

  • experimental_cross_link (ExperimentalCrossLink) – The corresponding cross-link identified by experiment. Multiple cross-links can map to a single experimental identification.

  • asym1 (ihm.AsymUnit) – The asymmetric unit containing the first linked residue.

  • asym2 (ihm.AsymUnit) – The asymmetric unit containing the second linked residue.

  • atom1 (str) – The name of the first linked atom.

  • atom2 (str) – The name of the second linked atom.

  • distance (DistanceRestraint) – Restraint on the distance.

  • psi (float) – Initial uncertainty in the experimental data.

  • sigma1 (float) – Initial uncertainty in the position of the first residue.

  • sigma2 (float) – Initial uncertainty in the position of the second residue.

  • restrain_all (bool) – If True, all cross-links are restrained.

  • pseudo1 (List of CrossLinkPseudoSite) – List of pseudo sites representing the position of the first residue (if applicable).

  • pseudo2 (List of CrossLinkPseudoSite) – List of pseudo sites representing the position of the second residue (if applicable).

fits

Information about the fit of each model to this cross-link. This is a Python dict where keys are Model objects and values are CrossLinkFit objects.

class ihm.restraint.CrossLinkFit(psi=None, sigma1=None, sigma2=None)[source]

Information on the fit of a model to a CrossLink. See ResidueCrossLink.fits, AtomCrossLink.fits, or FeatureCrossLink.fits.

Parameters:

  • psi (float) – Uncertainty in the experimental data.

  • sigma1 (float) – Uncertainty in the position of the first residue.

  • sigma2 (float) – Uncertainty in the position of the second residue.

class ihm.restraint.Feature[source]

Base class for selecting parts of the system that a restraint acts on. See ResidueFeature, AtomFeature, NonPolyFeature, and PseudoSiteFeature.

Features are typically assigned to one or more GeometricRestraint or DerivedDistanceRestraint objects.

class ihm.restraint.ResidueFeature(ranges, details=None)[source]

Selection of one or more residues from the system.

Residues can be selected from both ihm.AsymUnit and ihm.Entity (the latter implies that it selects residues in all instances of that entity). Individual residues can also be selected by passing ihm.Residue objects.

Parameters:
class ihm.restraint.AtomFeature(atoms, details=None)[source]

Selection of one or more atoms from the system. Atoms can be selected from polymers or non-polymers (but not both). Atoms can also be selected from both ihm.AsymUnit and ihm.Entity (the latter implies that it selects atoms in all instances of that entity). For selecting an entire polymer or residue(s), see ResidueFeature. For selecting an entire non-polymer, see NonPolyFeature.

Parameters:

  • atoms (sequence) – A list of ihm.Atom objects.

  • details (str) – Additional text describing this feature.

class ihm.restraint.NonPolyFeature(objs, details=None)[source]

Selection of one or more non-polymers from the system. To select individual atoms from a non-polymer, see AtomFeature.

Features can include both ihm.AsymUnit and ihm.Entity (the latter implies that it selects non-polymers in all instances of that entity).

Parameters:

  • objs (sequence) – A list of ihm.AsymUnit and/or ihm.Entity objects.

  • details (str) – Additional text describing this feature.

class ihm.restraint.PseudoSiteFeature(site)[source]

Selection of a pseudo position in the system.

Parameters:

site (PseudoSite) – The pseudo site to use for the feature.

class ihm.restraint.GeometricRestraint(dataset, geometric_object, feature, distance, harmonic_force_constant=None, restrain_all=None, pseudo1=None, pseudo2=None)[source]

A restraint between part of the system and some part of a geometric object. See CenterGeometricRestraint, InnerSurfaceGeometricRestraint, OuterSurfaceGeometricRestraint.

Parameters:

  • dataset (Dataset) – Reference to the data from which the restraint is derived.

  • geometric_object (ihm.geometry.GeometricObject) – The geometric object to restrain against.

  • feature (Feature) – The part of the system to restrain.

  • distance (DistanceRestraint) – Restraint on the distance.

  • harmonic_force_constant (float) – Force constant, if applicable.

  • restrain_all (bool) – If True, all distances are restrained.

class ihm.restraint.CenterGeometricRestraint(dataset, geometric_object, feature, distance, harmonic_force_constant=None, restrain_all=None, pseudo1=None, pseudo2=None)[source]

A restraint between part of the system and the center of a geometric object. See GeometricRestraint for a description of the parameters.

class ihm.restraint.InnerSurfaceGeometricRestraint(dataset, geometric_object, feature, distance, harmonic_force_constant=None, restrain_all=None, pseudo1=None, pseudo2=None)[source]

A restraint between part of the system and the inner surface of a geometric object. See GeometricRestraint for a description of the parameters.

class ihm.restraint.OuterSurfaceGeometricRestraint(dataset, geometric_object, feature, distance, harmonic_force_constant=None, restrain_all=None, pseudo1=None, pseudo2=None)[source]

A restraint between part of the system and the outer surface of a geometric object. See GeometricRestraint for a description of the parameters.

class ihm.restraint.DerivedDistanceRestraint(dataset, feature1, feature2, distance, probability=None, restrain_all=None, mic_value=None)[source]

A restraint between two parts of the system, derived from experimental data.

Parameters:

  • dataset (Dataset) – Reference to the data from which the restraint is derived.

  • feature1 (Feature) – The first part of the system to restrain.

  • feature2 (Feature) – The second part of the system to restrain.

  • distance (DistanceRestraint) – Restraint on the distance.

  • probability (float) – Likelihood that restraint is correct (0. - 1.)

  • restrain_all (bool) – If True, all distances are restrained.

  • mic_value (float) – Value of the Maximal Information Coefficient (MIC) for this interaction, if applicable.

class ihm.restraint.PredictedContactRestraint(dataset, resatom1, resatom2, distance, by_residue, probability=None, software=None)[source]

A predicted contact between two parts of the system, derived from various computational tools.

Parameters:

  • dataset (Dataset) – Reference to the data from which the restraint is derived.

  • resatom1 (ihm.Residue or ihm.Atom) – The first residue or atom to restrain.

  • resatom2 (ihm.Residue or ihm.Atom) – The second residue or atom to restrain.

  • distance (DistanceRestraint) – Restraint on the distance.

  • by_residue (bool) – If True, the restraint is applied to specific residues; otherwise, it is applied to the closest primitive object with the highest resolution.

  • probability (float) – Likelihood that restraint is correct (0. - 1.)

  • software (Software) – The software used to generate the contact.