The ihm.model Python module

Classes for handling models (sets of coordinates) as well as groups of models.

class ihm.model.Sphere(asym_unit, seq_id_range, x, y, z, radius, rmsf=None)

Coordinates of part of the model represented by a sphere.

See Model.get_spheres() for more details.

Parameters:

• asym_unit (ihm.AsymUnit) – The asymmetric unit that this sphere represents

• seq_id_range (tuple) – The range of residues represented by this sphere (as a two-element tuple)

• x (float) – x coordinate of the center of the sphere

• y (float) – y coordinate of the center of the sphere

• z (float) – z coordinate of the center of the sphere

• radius (float) – radius of the sphere

• rmsf (float) – root-mean-square fluctuation of the coordinates

class ihm.model.Atom(asym_unit, seq_id, atom_id, type_symbol, x, y, z, het=False, biso=None, occupancy=None, alt_id=None)

Coordinates of part of the model represented by an atom.

See Model.get_atoms() for more details. Note that this class is used only to represent the coordinates of an atom. To access atom-specific properties of the model, see the ihm.Atom class.

Parameters:

• asym_unit (ihm.AsymUnit) – The asymmetric unit that this atom represents

• seq_id (int) – The sequence ID of the residue represented by this atom. This should generally be a number starting at 1 for any polymer chain, water, or oligosaccharide. For ligands, a seq_id is not needed (as a given asym can only contain a single ligand), so either 1 or None can be used.

• atom_id (str) – The name of the atom in the residue

• type_symbol (str) – Element name

• x (float) – x coordinate of the atom

• y (float) – y coordinate of the atom

• z (float) – z coordinate of the atom

• het (bool) – True for HETATM sites, False (default) for ATOM

• biso (float) – Temperature factor or equivalent (if applicable)

• occupancy (float) – Fraction of the atom type present (if applicable)

• alt_id (float) – Alternate conformation indicator (if applicable)

class ihm.model.Model(assembly, protocol, representation, name=None)

A single set of coordinates (conformation).

Models are added to the system by placing them inside ModelGroup objects, which in turn are placed inside State objects, which are grouped in StateGroup objects, which are finally added to the system via ihm.System.state_groups.

Parameters:

• assembly (Assembly) – The parts of the system that were modeled.

• protocol (Protocol) – Description of how the modeling was done.

• representation (Representation) – Level of detail at which the system was represented.

• name (str) – Descriptive name for this model.

add_atom(atom)

Add to the model’s set of Atom objects.

See get_spheres() for more details.

Note that for branched entities, the seq_id of the new atom is provisional. It should be mapped to the correct ID once the input file is completely read, using ihm.AsymUnit.num_map. This is done automatically by ihm.reader when using the default implementation.

add_sphere(sphere)

Add to the model’s set of Sphere objects.

See get_spheres() for more details.

get_atoms()

Yield Atom objects that represent this model.

See get_spheres() for more details.

get_spheres()

Yield Sphere objects that represent this model.

The default implementation simply iterates over an internal list of spheres, but this is not very memory-efficient, particularly if the spheres are already stored somewhere else, e.g. in the software’s own data structures. It is recommended to subclass and provide a more efficient implementation. For example, the modeling of Nup133 uses a custom subclass to pass BioPython objects through to python-ihm.

Note that the set of spheres should match the model’s Representation. This is not currently enforced.

not_modeled_residue_ranges

List of residue ranges that were explicitly not modeled. See NotModeledResidueRange.

class ihm.model.ModelRepresentative(model, selection_criteria)

A single model that represents all models in a ModelGroup. See ModelGroup.representatives.

Parameters:

• model (Model) – The actual representative Model.

• selection_criteria (str) – How the representative was chosen

property selection_criteria

How the representative was chosen

class ihm.model.ModelGroup(elements=(), name=None, details=None)

A set of related models. See Model. It is implemented as a simple list of the models.

These objects are typically stored in a State, Ensemble, or OrderedProcess.

Parameters:

• elements – Initial set of models in the group.

• name (str) – Descriptive name for the group.

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

representatives

Any representative structural model(s). See ModelRepresentative.

class ihm.model.State(elements=(), type=None, name=None, details=None, experiment_type=None, population_fraction=None)

A set of model groups that constitute a single state of the system. It is implemented as a simple list of the model groups. See StateGroup.

Parameters:

elements – The initial set of ModelGroup objects in this state.

class ihm.model.StateGroup(elements=())

A set of related states. See State and ihm.System.state_groups. It is implemented as a simple list of the states.

Parameters:

elements – Initial set of states in the group.

class ihm.model.Ensemble(model_group, num_models, post_process=None, clustering_method=None, clustering_feature=None, name=None, precision=None, file=None, details=None, superimposed=None)

Details about a model cluster or ensemble. See ihm.System.ensembles.

Parameters:

• model_group (ModelGroup) – The set of models in this ensemble.

• num_models (int) – The total number of models in this ensemble. This may be more than the number of models in model_group, for example if only representative or top-scoring models are deposited.

• post_process (ihm.analysis.Step) – The final analysis step that generated this ensemble.

• clustering_method (str) – The method used to obtain the ensemble, if applicable.

• clustering_feature (str) – The feature used for clustering the models, if applicable.

• name (str) – A descriptive name for this ensemble.

• precision (float) – The precision of the entire ensemble.

• file (ihm.location.OutputFileLocation) – A reference to an external file containing coordinates for the entire ensemble, for example as a DCD file (see DCDWriter). See also subsamples.

• details (str) – Additional text describing this ensemble

• superimposed (bool) – True if the models in the group are structurally aligned.

property clustering_feature

The feature used for clustering the models, if applicable

property clustering_method

The clustering method used to obtain the ensemble, if applicable

densities

All localization densities for this ensemble, as LocalizationDensity objects

property num_models_deposited

Number of models in this ensemble that are in the mmCIF file

subsamples

All subsamples that make up this ensemble (if applicable), as Subsample objects

class ihm.model.NotModeledResidueRange(asym_unit, seq_id_begin, seq_id_end, reason=None)

A range of residues that were explicitly not modeled. See Model.not_modeled_residue_ranges.

Parameters:

• asym_unit (AsymUnit) – The asymmetric unit to which the residues belong.

• seq_id_begin (int) – Starting residue in the range.

• seq_id_end (int) – Ending residue in the range.

• reason (str) – Optional text describing why the residues were not modeled.

property reason

Reason why the residues were not modeled.

class ihm.model.OrderedProcess(ordered_by, description=None)

Details about a process that orders two or more model groups.

A process is represented as a directed graph, where the nodes are ModelGroup objects and the edges represent transitions.

These objects are generally added to ihm.System.ordered_processes.

Parameters:

• ordered_by (str) – Text that explains how the ordering is done, such as “time steps”.

• description (str) – Text that describes this process.

steps

All steps in this process, as a simple list of ProcessStep objects

class ihm.model.ProcessStep(elements=(), description=None)

A single step in an OrderedProcess.

This is implemented as a simple list of ProcessEdge objects, each of which orders two ModelGroup objects. (To order more than two groups, for example to represent a branched reaction step that generates two products, simply add multiple edges to the step.)

Parameters:

• elements (sequence) – Initial set of ProcessEdge objects.

• description (str) – Text that describes this step.

class ihm.model.ProcessEdge(group_begin, group_end, description=None)

A single directed edge in the graph for a OrderedProcess, representing the transition from one ModelGroup to another. These objects are added to ProcessStep objects.

Parameters:

• group_begin (ModelGroup) – The set of models at the origin of the edge.

• group_end (ModelGroup) – The set of models at the end of the edge.

• description (str) – Text that describes this edge.

class ihm.model.LocalizationDensity(file, asym_unit)

Localization density of part of the system, over all models in an ensemble.

See Ensemble.densities.

Parameters:

• file (ihm.location.OutputFileLocation) – A reference to an external file containing the density, for example as an MRC file.

• asym_unit (AsymUnit or AsymUnitRange) – The asymmetric unit (or part of one) that this density represents.

class ihm.model.DCDWriter(fh)

Utility class to write model coordinates to a binary DCD file.

See Ensemble and Model. Since mmCIF is a text-based format, it is not efficient to store entire ensembles in this format. Instead, representative models should be deposited as mmCIF and the Ensemble then linked to an external file containing only model coordinates. One such format is CHARMM/NAMD’s DCD, which is written out by this class. The DCD files simply contain the xyz coordinates of all Atom and Sphere objects in each Model. (Note that no other data is stored, such as sphere radii or restraint parameters.)

Parameters:

fh (file) – The filelike object to write the coordinates to. This should be open in binary mode and should be a seekable object.

add_model(model)

Add the coordinates for the given Model to the file as a new frame. All models in the file should have the same number of atoms and/or spheres, in the same order.

Parameters:

model (Model) – Model with coordinates to write to the file.

class ihm.model.Subsample(name, num_models, model_group=None, file=None)

Base class for a subsample within an ensemble.

In some cases the models that make up an Ensemble may be partitioned into subsamples, for example to determine if the sampling was exhaustive (see Viswanath et al. 2017). This base class can be used to describe the set of models in the subsample, for example by pointing to an externally-deposited set of conformations.

Usually a derived class (RandomSubsample or IndependentSubsample) is used instead of this class. Instances are stored in Ensemble.subsamples. All of the subsamples in a given ensemble must be of the same type.

Parameters:

• name (str) – A descriptive name for this sample

• num_models (int) – The total number of models in this sample

• model_group (ModelGroup) – The set of models in this sample, if applicable.

• file (ihm.location.OutputFileLocation) – A reference to an external file containing coordinates for the entire sample, for example as a DCD file (see DCDWriter).

property num_models_deposited

Number of models in this subsample that are in the mmCIF file

class ihm.model.RandomSubsample(name, num_models, model_group=None, file=None)

A subsample generated by picking a random subset of the models that make up the entire ensemble. See Subsample.

class ihm.model.IndependentSubsample(name, num_models, model_group=None, file=None)

A subsample generated in the same fashion as other subsamples but by an independent simulation. See Subsample.