11.2.1. Core Topology object — MDAnalysis.core.topology¶
New in version 0.16.0.
Topology is the core object that holds all topology information.
TODO: Add in-depth discussion.
Notes
For developers: In MDAnalysis 0.16.0 this new topology system was introduced and discussed as issue #363; this issue contains key information and discussions on the new system. The issue number 363 is also being used as a short-hand in discussions to refer to the new topology system.
11.2.1.1. Classes¶
-
class
MDAnalysis.core.topology.Topology(n_atoms=1, n_res=1, n_seg=1, attrs=None, atom_resindex=None, residue_segindex=None)[source]¶ In-memory, array-based topology database.
The topology model of MDanalysis features atoms, which must each be a member of one residue. Each residue, in turn, must be a member of one segment. The details of maintaining this heirarchy, and mappings of atoms to residues, residues to segments, and vice-versa, are handled internally by this object.
Parameters: - n_atoms (int) – number of atoms in topology. Must be larger then 1 at each level
- n_residues (int) – number of residues in topology. Must be larger then 1 at each level
- n_segments (int) – number of segments in topology. Must be larger then 1 at each level
- attrs (TopologyAttr objects) – components of the topology to be included
- atom_resindex (array) – 1-D array giving the resindex of each atom in the system
- residue_segindex (array) – 1-D array giving the segindex of each residue in the system
-
add_Residue(segment, **new_attrs)[source]¶ Returns: Return type: residx of the new Residue Raises: NoDataError– If not all data was provided. This error is raised before any
-
add_TopologyAttr(topologyattr)[source]¶ Add a new TopologyAttr to the Topology.
Parameters: topologyattr (TopologyAttr) –
-
guessed_attributes¶ A list of the guessed attributes in this topology
-
read_attributes¶ A list of the attributes read from the topology
-
class
MDAnalysis.core.topology.TransTable(n_atoms, n_residues, n_segments, atom_resindex=None, residue_segindex=None)[source]¶ Membership tables with methods to translate indices across levels.
There are three levels; Atom, Residue and Segment. Each Atom must belong in a Residue, each Residue must belong to a Segment.
When translating upwards, eg finding which Segment a Residue belongs in, a single numpy array is returned. When translating downwards, two options are available; a concatenated result (suffix _1) or a list for each parent object (suffix _2d).
Parameters: - n_atoms (int) – number of atoms in topology
- n_residues (int) – number of residues in topology
- n_segments (int) – number of segments in topology
- atom_resindex (1-D array) – resindex for each atom in the topology; the number of unique values in this array must be <= n_residues, and the array must be length n_atoms; giving None defaults to placing all atoms in residue 0
- residue_segindex (1-D array) – segindex for each residue in the topology; the number of unique values in this array must be <= n_segments, and the array must be length n_residues; giving None defaults to placing all residues in segment 0
-
size¶ tuple describing the shape of the TransTable
-
atoms2residues(aix)[source] Get residue indices for each atom.
Parameters: aix (array) – atom indices Returns: rix – residue index for each atom Return type: array
-
atoms2segments(aix)[source] Get segment indices for each atom.
Parameters: aix (array) – atom indices Returns: rix – segment index for each atom Return type: array
-
residues2atoms_1d(rix)[source] Get atom indices collectively represented by given residue indices.
Parameters: rix (array) – residue indices Returns: aix – indices of atoms present in residues, collectively Return type: array
-
residues2atoms_2d(rix)[source] Get atom indices represented by each residue index.
Parameters: rix (array) – residue indices Returns: raix – each element corresponds to a residue index, in order given in rix, with each element being an array of the atom indices present in that residue Return type: list
-
residues2segments(rix)[source] Get segment indices for each residue.
Parameters: rix (array) – residue indices Returns: six – segment index for each residue Return type: array
-
segments2atoms_1d(six)[source] Get atom indices collectively represented by given segment indices.
Parameters: six (array) – segment indices Returns: aix – sorted indices of atoms present in segments, collectively Return type: array
-
segments2atoms_2d(six)[source] Get atom indices represented by each segment index.
Parameters: six (array) – residue indices Returns: saix – each element corresponds to a segment index, in order given in six, with each element being an array of the atom indices present in that segment Return type: list
-
segments2residues_1d(six)[source] Get residue indices collectively represented by given segment indices
Parameters: six (array) – segment indices Returns: rix – sorted indices of residues present in segments, collectively Return type: array
-
segments2residues_2d(six)[source] Get residue indices represented by each segment index.
Parameters: six (array) – residue indices Returns: srix – each element corresponds to a segment index, in order given in six, with each element being an array of the residue indices present in that segment Return type: list
-
size The shape of the table, (n_atoms, n_residues, n_segments)
11.2.1.2. Helper functions¶
-
MDAnalysis.core.topology.make_downshift_arrays(upshift, nparents)[source]¶ From an upwards translation table, create the opposite direction
Turns a many to one mapping (eg atoms to residues) to a one to many mapping (residues to atoms)
Parameters: - upshift (array_like) – Array of integers describing which parent each item belongs to
- nparents (integer) – Total number of parents that exist.
Returns: downshift – An array of arrays, each containing the indices of the children of each parent. Length nparents + 1
Return type: array_like (dtype object)
Examples
To find the residue to atom mappings for a given atom to residue mapping:
>>> atom2res = np.array([0, 1, 0, 2, 2, 0, 2]) >>> make_downshift_arrays(atom2res) array([array([0, 2, 5]), array([1]), array([3, 4, 6]), None], dtype=object)
Entry 0 corresponds to residue 0 and says that this contains atoms 0, 2 & 5
Notes
The final entry in the return array will be
Noneto ensure that the dtype of the array isobject.Warning
This means negative indexing should never be used with these arrays.