11.1.2. Core objects: Containers — MDAnalysis.core.groups¶
The Universe instance contains all the
particles in the system (which MDAnalysis calls Atom). Groups of
atoms are handled as AtomGroup instances. The
AtomGroup is probably the most important object in MDAnalysis because
virtually everything can be accessed through it. AtomGroup instances
can be easily created (e.g., from an AtomGroup.select_atoms() selection or
simply by slicing).
For convenience, chemically meaningful groups of Atoms such as a
Residue or a Segment (typically a whole molecule or all of the
solvent) also exist as containers, as well as groups of these units
(ResidueGroup, SegmentGroup).
11.1.2.1. Classes¶
11.1.2.1.1. Collections¶
-
class
MDAnalysis.core.groups.AtomGroup(*args)[source]¶ An ordered array of atoms.
Can be initiated from an iterable of
Atoms:ag = AtomGroup([Atom1, Atom2, Atom3])
Or from providing a list of indices and the
Universeit should belong to:ag = AtomGroup([72, 14, 25], u)
Alternatively, an
AtomGroupis generated by indexing/slicing anotherAtomGroup, such as the group of allAtomsin theUniverseatMDAnalysis.core.universe.Universe.atoms.An
AtomGroupcan be indexed and sliced like a list:ag[0], ag[-1]
will return the first and the last
Atomin the group whereas the slice:ag[0:6:2]
returns an
AtomGroupof every second element, corresponding to indices 0, 2, and 4.It also supports “advanced slicing” when the argument is a
numpy.ndarrayor alist:aslice = [0, 3, -1, 10, 3] ag[aslice]
will return a new
AtomGroupofAtomswith those indices in the oldAtomGroup.Finally,
AtomGroupscan be created from a selection. Seeselect_atoms().Note
AtomGroupsoriginating from a selection are sorted and duplicate elements are removed. This is not true forAtomGroupsproduced by slicing. Thus, slicing can be used when the order of atoms is crucial (for instance, in order to define angles or dihedrals).AtomGroupscan be compared and combined using group operators. For instance,AtomGroupscan be concatenated using + orconcatenate():ag_concat = ag1 + ag2 # or ag_concat = ag1.concatenate(ag2)
When groups are concatenated, the order of the
Atomsis conserved. IfAtomsappear several times in one of the groups, the duplicates are kept in the resulting group. On the contrary toconcatenate(),union()treats theAtomGroupsas sets so that duplicates are removed from the resulting group, andAtomsare ordered. The | operator is synomymous tounion():ag_union = ag1 | ag2 # or ag_union = ag1.union(ag2)
The opposite operation to
concatenate()issubtract(). This method creates a new group with all theAtomsof the group that are not in a given other group; the order of theAtomsis kept, and so are duplicates.difference()is the set version ofsubtract(). The resulting group is sorted and deduplicated.All set methods are listed in the table below. These methods treat the groups as sorted and deduplicated sets of
Atoms.Operation Equivalent Result s.isdisjoint(t)Trueifsandtdo not share elementss.issubset(t)test if all elements of sare part ofts.is_strict_subset(t)test if all elements of sare part oft, ands != ts.issuperset(t)test if all elements of tare part ofss.is_strict_superset(t)test if all elements of tare part ofs, ands != ts.union(t)s | tnew Group with elements from both sandts.intersection(t)s & tnew Group with elements common to sandts.difference(t)s - tnew Group with elements of sthat are not ints.symmetric_difference(t)s ^ tnew Group with elements that are part of sortbut not bothThe following methods keep the order of the atoms as well as duplicates.
Operation Equivalent Result len(s)number of elements (atoms, residues or segment) in the group s == ttest if sandtcontain the same elements in the same orders.concatenate(t)s + tnew Group with elements from sand fromts.subtract(t)new Group with elements from sthat are not intThe in operator allows to test if an
Atomis in theAtomGroup.AtomGroupinstances are always bound to aMDAnalysis.core.universe.Universe. They cannot exist in isolation.See also
MDAnalysis.core.universe.Universe- Instant selectors of
AtomGroupwill be removed in the 1.0 release. - Removed instant selectors, use select_atoms(‘name …’) to select atoms by name.
-
accumulate(attribute, function=<function sum>, compound='group')¶ Accumulates the attribute associated with (compounds of) the group.
Accumulates the attribute of
Atomsin the group. The accumulation perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly. By default, the method sums up all attributes per compound, but any function that takes an array and returns an acuumulation over a given axis can be used. For multi-dimensional input arrays, the accumulation is performed along the first axis.Parameters: - attribute (str or array_like) – Attribute or array of values to accumulate.
If a
numpy.ndarray(or compatible) is provided, its first dimension must have the same length as the total number of atoms in the group. - function (callable, optional) – The function performing the accumulation. It must take the array of
attribute values to accumulate as its only positional argument and
accept an (optional) keyword argument
axisallowing to specify the axis along which the accumulation is performed. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the accumulation of all attributes associated with atoms in the group will be returned as a single value. Otherwise, the accumulation of the attributes perSegment,Residue, molecule, or fragment will be returned as a 1d array. Note that, in any case, only theAtomsbelonging to the group will be taken into account.
Returns: Acuumulation of the attribute. If compound is set to
'group', the first dimension of the attribute array will be contracted to a single value. If compound is set to'segments','residues','molecules', or'fragments', the length of the first dimension will correspond to the number of compounds. In all cases, the other dimensions of the returned array will be of the original shape (without the first dimension).Return type: Raises: ValueError– If the length of a provided attribute array does not correspond to the number of atoms in the group.ValueError– If compound is not one of'group','segments','residues','molecules', or'fragments'.NoDataError– If compound is'molecule'but the topology doesn’t contain molecule information (molnums), or if compound is'fragments'but the topology doesn’t contain bonds.
Examples
To find the total charge of a given
AtomGroup:>>> sel = u.select_atoms('prop mass > 4.0') >>> sel.accumulate('charges')
To find the total mass per residue of all CA
Atoms:>>> sel = u.select_atoms('name CA') >>> sel.accumulate('masses', compound='residues')
To find the maximum atomic charge per fragment of a given
AtomGroup:>>> sel.accumulate('charges', compound="fragments", function=np.max)
New in version 0.20.0.
- attribute (str or array_like) – Attribute or array of values to accumulate.
If a
-
angle¶ This
AtomGrouprepresented as anMDAnalysis.core.topologyobjects.AngleobjectRaises: ValueError– If theAtomGroupis not length 3New in version 0.11.0.
-
atoms¶ The
AtomGroupitself.Changed in version 0.19.0: In previous versions, this returned a copy, but now the
AtomGroupitself is returned. This should not affect any code but only speed up calculations.
-
bbox(pbc=False)¶ Return the bounding box of the selection.
The lengths A,B,C of the orthorhombic enclosing box are
L = AtomGroup.bbox() A,B,C = L[1] - L[0]
Parameters: pbc (bool, optional) – If True, move allAtomsto the primary unit cell before calculation. [False]Returns: corners – 2x3 array giving corners of bounding box as [[xmin, ymin, zmin], [xmax, ymax, zmax]].Return type: numpy.ndarray New in version 0.7.2.
Changed in version 0.8: Added pbc keyword
Changed in version 1.0.0: Removed flags affecting default behaviour
-
bond¶ This
AtomGrouprepresented as aMDAnalysis.core.topologyobjects.BondobjectRaises: ValueError– If theAtomGroupis not length 2New in version 0.11.0.
-
bsphere(pbc=False)¶ Return the bounding sphere of the selection.
The sphere is calculated relative to the
center of geometry.Parameters: pbc (bool, optional) – If True, move all atoms to the primary unit cell before calculation. [False]Returns: - R (float) – Radius of the bounding sphere.
- center (numpy.ndarray) – Coordinates of the sphere center as
[xcen, ycen, zcen].
New in version 0.7.3.
Changed in version 0.8: Added pbc keyword
-
center(weights, pbc=False, compound='group', unwrap=False)¶ Weighted center of (compounds of) the group
Computes the weighted center of
Atomsin the group. Weighted centers perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the weights of a compound sum up to zero, the coordinates of that compound’s weighted center will benan(not a number).Parameters: - weights (array_like or None) – Weights to be used. Setting weights=None is equivalent to passing identical weights for all atoms of the group.
- pbc (bool, optional) – If
Trueand compound is'group', move all atoms to the primary unit cell before calculation. IfTrueand compound is'segments','residues','molecules', or'fragments', the center of each compound will be calculated without moving anyAtomsto keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default [False]. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the weighted center of all atoms in the group will be returned as a single position vector. Else, the weighted centers of eachSegment,Residue, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions ofAtomsbelonging to the group will be taken into account. - unwrap (bool, optional) – If
True, compounds will be unwrapped before computing their centers.
Returns: center – Position vector(s) of the weighted center(s) of the group. If compound was set to
'group', the output will be a single position vector. If compound was set to'segments','residues','molecules', or'fragments', the output will be a 2d array of shape(n, 3)wherenis the number of compounds.Return type: Raises: ValueError– If compound is not one of'group','segments','residues','molecules', or'fragments'.ValueError– If both ‘pbc’ and ‘unwrap’ set to true.NoDataError– If compound is'molecule'but the topology doesn’t contain molecule information (molnums) or if compound is'fragments'but the topology doesn’t contain bonds.
Examples
To find the center of charge of a given
AtomGroup:>>> sel = u.select_atoms('prop mass > 4.0') >>> sel.center(sel.charges)
To find the centers of mass per residue of all CA
Atoms:>>> sel = u.select_atoms('name CA') >>> sel.center(sel.masses, compound='residues')
Changed in version 0.19.0: Added compound parameter
Changed in version 0.20.0: Added
'molecules'and'fragments'compoundsChanged in version 0.20.0: Added unwrap parameter
Changed in version 1.0.0: Removed flags affecting default behaviour
-
center_of_geometry(pbc=False, compound='group', unwrap=False)¶ Center of geometry of (compounds of) the group.
Computes the center of geometry (a.k.a. centroid) of
Atomsin the group. Centers of geometry perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly.Parameters: - pbc (bool, optional) – If
Trueand compound is'group', move all atoms to the primary unit cell before calculation. IfTrueand compound is'segments'or'residues', the center of each compound will be calculated without moving anyAtomsto keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the center of geometry of allAtomsin the group will be returned as a single position vector. Else, the centers of geometry of eachSegmentorResiduewill be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions ofAtomsbelonging to the group will be taken into account. - unwrap (bool, optional) – If
True, compounds will be unwrapped before computing their centers.
Returns: center – Position vector(s) of the geometric center(s) of the group. If compound was set to
'group', the output will be a single position vector. If compound was set to'segments'or'residues', the output will be a 2d array of shape(n, 3)wherenis the number of compounds.Return type: Changed in version 0.8: Added pbc keyword
Changed in version 0.19.0: Added compound parameter
Changed in version 0.20.0: Added
'molecules'and'fragments'compoundsChanged in version 0.20.0: Added unwrap parameter
Changed in version 1.0.0: Removed flags affecting default behaviour
- pbc (bool, optional) – If
-
centroid(pbc=False, compound='group', unwrap=False)¶ Center of geometry of (compounds of) the group.
Computes the center of geometry (a.k.a. centroid) of
Atomsin the group. Centers of geometry perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly.Parameters: - pbc (bool, optional) – If
Trueand compound is'group', move all atoms to the primary unit cell before calculation. IfTrueand compound is'segments'or'residues', the center of each compound will be calculated without moving anyAtomsto keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the center of geometry of allAtomsin the group will be returned as a single position vector. Else, the centers of geometry of eachSegmentorResiduewill be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions ofAtomsbelonging to the group will be taken into account. - unwrap (bool, optional) – If
True, compounds will be unwrapped before computing their centers.
Returns: center – Position vector(s) of the geometric center(s) of the group. If compound was set to
'group', the output will be a single position vector. If compound was set to'segments'or'residues', the output will be a 2d array of shape(n, 3)wherenis the number of compounds.Return type: Changed in version 0.8: Added pbc keyword
Changed in version 0.19.0: Added compound parameter
Changed in version 0.20.0: Added
'molecules'and'fragments'compoundsChanged in version 0.20.0: Added unwrap parameter
Changed in version 1.0.0: Removed flags affecting default behaviour
- pbc (bool, optional) – If
-
cmap¶ This
AtomGrouprepresented as anMDAnalysis.core.topologyobjects.CMapobjectRaises: ValueError– If theAtomGroupis not length 5New in version 1.0.0.
-
concatenate(other)¶ Concatenate with another Group or Component of the same level.
Duplicate entries and original order is preserved. It is synomymous to the + operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with elements of self and other concatenated Return type: Group Example
The order of the original contents (including duplicates) are preserved when performing a concatenation.
>>> ag1 = u.select_atoms('name O') >>> ag2 = u.select_atoms('name N') >>> ag3 = ag1 + ag2 # or ag1.concatenate(ag2) >>> ag3[:3].names array(['O', 'O', 'O'], dtype=object) >>> ag3[-3:].names array(['N', 'N', 'N'], dtype=object)
New in version 0.16.0.
-
convert_to(package)[source]¶ Convert
AtomGroupto a structure from another Python package.Example
The code below converts a Universe to a
parmed.structure.Structure.>>> import MDAnalysis as mda >>> from MDAnalysis.tests.datafiles import GRO >>> u = mda.Universe(GRO) >>> parmed_structure = u.atoms.convert_to('PARMED') >>> parmed_structure <Structure 47681 atoms; 11302 residues; 0 bonds; PBC (triclinic); NOT parametrized>
Parameters: package (str) – The name of the package to convert to, e.g. "PARMED"Returns: An instance of the structure type from another package. Return type: output Raises: TypeError: – No converter was found for the required package New in version 1.0.0.
-
copy()¶ Get another group identical to this one.
New in version 0.19.0.
-
difference(other)¶ Elements from this Group that do not appear in another
This method removes duplicate elements and sorts the result. As such, it is different from
subtract().difference()is synomymous to the - operator.Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the elements of self that are not in other, without duplicate elements Return type: Group See also
New in version 0.16.
-
dihedral¶ This
AtomGrouprepresented as aDihedralobjectRaises: ValueError– If theAtomGroupis not length 4New in version 0.11.0.
-
dimensions¶ Obtain a copy of the dimensions of the currently loaded Timestep
-
forces¶ Forces on each
Atomin theAtomGroup.A
numpy.ndarraywithshape=(n_atoms, 3)anddtype=numpy.float32.The forces can be changed by assigning an array of the appropriate shape, i.e. either
(n_atoms, 3)to assign individual forces or(3,)to assign the same force to allAtoms(e.g.ag.forces = array([0,0,0])will give allAtomsa zeroforce).Raises: NoDataError– If theTimestepdoes not containforces.
-
groupby(topattrs)¶ Group together items in this group according to values of topattr
Parameters: topattrs (str or list) – One or more topology attributes to group components by. Single arguments are passed as a string. Multiple arguments are passed as a list. Returns: Unique values of the multiple combinations of topology attributes as keys, Groups as values. Return type: dict Example
To group atoms with the same mass together:
>>> ag.groupby('masses') {12.010999999999999: <AtomGroup with 462 atoms>, 14.007: <AtomGroup with 116 atoms>, 15.999000000000001: <AtomGroup with 134 atoms>}
To group atoms with the same residue name and mass together:
>>> ag.groupby(['resnames', 'masses']) {('ALA', 1.008): <AtomGroup with 95 atoms>, ('ALA', 12.011): <AtomGroup with 57 atoms>, ('ALA', 14.007): <AtomGroup with 19 atoms>, ('ALA', 15.999): <AtomGroup with 19 atoms>}, ('ARG', 1.008): <AtomGroup with 169 atoms>, ...}
>>> ag.groupby(['resnames', 'masses'])('ALA', 15.999) <AtomGroup with 19 atoms>
New in version 0.16.0.
Changed in version 0.18.0: The function accepts multiple attributes
-
guess_bonds(vdwradii=None)[source]¶ Guess bonds that exist within this
AtomGroupand add them to the underlyinguniverse.Parameters: vdwradii (dict, optional) – Dict relating atom types: vdw radii New in version 0.10.0.
Changed in version 0.20.2: Now applies periodic boundary conditions when guessing bonds.
-
improper¶ This
AtomGrouprepresented as anMDAnalysis.core.topologyobjects.ImproperDihedralobjectRaises: ValueError– If theAtomGroupis not length 4New in version 0.11.0.
-
intersection(other)¶ Group of elements which are in both this Group and another
This method removes duplicate elements and sorts the result. It is synomymous to the & operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the common elements of self and other, without duplicate elements Return type: Group Example
Intersections can be used when the select atoms string would become too complicated. For example to find the water atoms which are within 4.0A of two segments:
>>> shell1 = u.select_atoms('resname SOL and around 4.0 segid 1') >>> shell2 = u.select_atoms('resname SOL and around 4.0 segid 2') >>> common = shell1 & shell2 # or shell1.intersection(shell2)
See also
New in version 0.16.
-
is_strict_subset(other)¶ If this Group is a subset of another Group but not identical
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a strict subset of the other oneReturn type: bool New in version 0.16.
-
is_strict_superset(other)¶ If this Group is a superset of another Group but not identical
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a strict superset of the other oneReturn type: bool New in version 0.16.
-
isdisjoint(other)¶ If the Group has no elements in common with the other Group
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif the two Groups do not have common elementsReturn type: bool New in version 0.16.
-
issubset(other)¶ If all elements of this Group are part of another Group
Note that an empty group is a subset of any group of the same level.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a subset of the other oneReturn type: bool New in version 0.16.
-
issuperset(other)¶ If all elements of another Group are part of this Group
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a subset of the other oneReturn type: bool New in version 0.16.
-
isunique¶ Boolean indicating whether all components of the group are unique, i.e., the group contains no duplicates.
Examples
>>> ag = u.atoms[[2, 1, 2, 2, 1, 0]] >>> ag <AtomGroup with 6 atoms> >>> ag.isunique False >>> ag2 = ag.unique >>> ag2 <AtomGroup with 3 atoms> >>> ag2.isunique True
New in version 0.19.0.
-
ix¶ Unique indices of the components in the Group.
- If this Group is an
AtomGroup, these are the indices of theAtominstances. - If it is a
ResidueGroup, these are the indices of theResidueinstances. - If it is a
SegmentGroup, these are the indices of theSegmentinstances.
- If this Group is an
-
ix_array¶ Unique indices of the components in the Group.
For a Group,
ix_arrayis the same asix. This method gives a consistent API between components and groups.See also
-
pack_into_box(box=None, inplace=True)¶ Shift all
Atomsin this group to the primary unit cell.Parameters: - box (array_like) – Box dimensions, can be either orthogonal or triclinic information.
Cell dimensions must be in an identical to format to those returned
by
MDAnalysis.coordinates.base.Timestep.dimensions,[lx, ly, lz, alpha, beta, gamma]. IfNone, uses these timestep dimensions. - inplace (bool) –
Trueto change coordinates in place.
Returns: coords – Shifted atom coordinates.
Return type: Notes
All atoms will be moved so that they lie between 0 and boxlength \(L_i\) in all dimensions, i.e. the lower left corner of the simulation box is taken to be at (0,0,0):
\[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\]The default is to take unit cell information from the underlying
Timestepinstance. The optional argument box can be used to provide alternative unit cell information (in the MDAnalysis standard format[Lx, Ly, Lz, alpha, beta, gamma]).Works with either orthogonal or triclinic box types.
Note
pack_into_box()is identical towrap()with all default keywords.Note
AtomGroup.pack_into_box()is currently faster thanResidueGroup.pack_into_box()orSegmentGroup.pack_into_box().New in version 0.8.
- box (array_like) – Box dimensions, can be either orthogonal or triclinic information.
Cell dimensions must be in an identical to format to those returned
by
-
positions¶ Coordinates of the
Atomsin theAtomGroup.A
numpy.ndarraywithshape=(n_atoms, 3)anddtype=numpy.float32.The positions can be changed by assigning an array of the appropriate shape, i.e., either
(n_atoms, 3)to assign individual coordinates, or(3,)to assign the same coordinate to allAtoms(e.g.,ag.positions = array([0,0,0])will move allAtomsto the origin).Note
Changing positions is not reflected in any files; reading any frame from the
trajectorywill replace the change with that from the file except if thetrajectoryis held in memory, e.g., when thetransfer_to_memory()method was used.Raises: NoDataError– If the underlyingTimestepdoes not containpositions.
-
residues¶ A sorted
ResidueGroupof the uniqueResiduespresent in theAtomGroup.
-
rotate(R, point=(0, 0, 0))¶ Apply a rotation matrix R to the selection’s coordinates. \(\mathsf{R}\) is a 3x3 orthogonal matrix that transforms a vector \(\mathbf{x} \rightarrow \mathbf{x}'\):
\[\mathbf{x}' = \mathsf{R}\mathbf{x}\]Atomcoordinates are rotated in-place.Parameters: - R (array_like) – 3x3 rotation matrix
- point (array_like, optional) – Center of rotation
Returns: Return type: self
Notes
By default, rotates about the origin
point=(0, 0, 0). To rotate a groupgaround its center of geometry, useg.rotate(R, point=g.center_of_geometry()).See also
rotateby()- rotate around given axis and angle
MDAnalysis.lib.transformations()- module of all coordinate transforms
-
rotateby(angle, axis, point=None)¶ Apply a rotation to the selection’s coordinates.
Parameters: - angle (float) – Rotation angle in degrees.
- axis (array_like) – Rotation axis vector.
- point (array_like, optional) – Center of rotation. If
Nonethen the center of geometry of this group is used.
Returns: Return type: self
Notes
The transformation from current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\) is
\[\mathbf{x}' = \mathsf{R}\,(\mathbf{x}-\mathbf{p}) + \mathbf{p}\]where \(\mathsf{R}\) is the rotation by angle around the axis going through point \(\mathbf{p}\).
See also
MDAnalysis.lib.transformations.rotation_matrix()calculate()- math:mathsf{R}
-
segments¶ A sorted
SegmentGroupof the unique segments present in theAtomGroup.
-
select_atoms(sel, *othersel, **selgroups)[source]¶ Select atoms from within this Group using a selection string.
Returns an
AtomGroupsorted according to their index in the topology (this is to ensure that there are no duplicates, which can happen with complicated selections).Parameters: - sel (str) – string of the selection, eg “name Ca”, see below for possibilities.
- othersel (iterable of str) – further selections to perform. The results of these selections will be appended onto the results of the first.
- periodic (bool (optional)) – for geometric selections, whether to account for atoms in different periodic images when searching
- updating (bool (optional)) – force the selection to be re evaluated each time the Timestep of the
trajectory is changed. See section on Dynamic selections below.
[
True] - **selgroups (keyword arguments of str: AtomGroup (optional)) – when using the “group” keyword in selections, groups are defined by passing them as keyword arguments. See section on preexisting selections below.
Raises: TypeError– If the arbitrary groups passed are not of typeMDAnalysis.core.groups.AtomGroupExamples
All simple selection listed below support multiple arguments which are implicitly combined with an or operator. For example
>>> sel = universe.select_atoms('resname MET GLY')
is equivalent to
>>> sel = universe.select_atoms('resname MET or resname GLY')
Will select all atoms with a residue name of either MET or GLY.
Subselections can be grouped with parentheses.
>>> sel = universe.select_atoms("segid DMPC and not ( name H* O* )") >>> sel <AtomGroup with 3420 atoms>
Existing
AtomGroupobjects can be passed as named arguments, which will then be available to the selection parser.>>> universe.select_atoms("around 10 group notHO", notHO=sel) <AtomGroup with 1250 atoms>
Selections can be set to update automatically on frame change, by setting the updating keyword argument to True. This will return a
UpdatingAtomGroupwhich can represent the solvation shell around another object.>>> universe.select_atoms("resname SOL and around 2.0 protein", updating=True) <Updating AtomGroup with 100 atoms>
Notes
If exact ordering of atoms is required (for instance, for
angle()ordihedral()calculations) then one supplies selections separately in the required order. Also, when multipleAtomGroupinstances are concatenated with the+operator, then the order ofAtominstances is preserved and duplicates are not removed.See also
Selection syntax
The selection parser understands the following CASE SENSITIVE keywords:
Simple selections
- protein, backbone, nucleic, nucleicbackbone
- selects all atoms that belong to a standard set of residues; a protein is identfied by a hard-coded set of residue names so it may not work for esoteric residues.
- segid seg-name
- select by segid (as given in the topology), e.g.
segid 4AKEorsegid DMPC - resid residue-number-range
- resid can take a single residue number or a range of numbers. A
range consists of two numbers separated by a colon (inclusive)
such as
resid 1:5. A residue number (“resid”) is taken directly from the topology. If icodes are present in the topology, then these will be taken into account. Ie ‘resid 163B’ will only select resid 163 with icode B while ‘resid 163’ will select only residue 163. Range selections will also respect icodes, so ‘resid 162-163B’ will select all residues in 162 and those in 163 up to icode B. - resnum resnum-number-range
- resnum is the canonical residue number; typically it is set to the residue id in the original PDB structure.
- resname residue-name
- select by residue name, e.g.
resname LYS - name atom-name
- select by atom name (as given in the topology). Often, this is
force field dependent. Example:
name CA(for Cα atoms) orname OW(for SPC water oxygen) - type atom-type
- select by atom type; this is either a string or a number and depends on the force field; it is read from the topology file (e.g. the CHARMM PSF file contains numeric atom types). It has non-sensical values when a PDB or GRO file is used as a topology
- atom seg-name residue-number atom-name
- a selector for a single atom consisting of segid resid atomname,
e.g.
DMPC 1 C2selects the C2 carbon of the first residue of the DMPC segment - altloc alternative-location
- a selection for atoms where alternative locations are available, which is often the case with high-resolution crystal structures e.g. resid 4 and resname ALA and altloc B selects only the atoms of ALA-4 that have an altloc B record.
- moltype molecule-type
- select by molecule type, e.g.
moltype Protein_A. At the moment, only the TPR format defines the molecule type. - record_type record_type
- for selecting either ATOM or HETATM from PDB-like files.
e.g.
select_atoms('name CA and not record_type HETATM')
Boolean
- not
- all atoms not in the selection, e.g.
not proteinselects all atoms that aren’t part of a protein - and, or
- combine two selections according to the rules of boolean
algebra, e.g.
protein and not resname ALA LYSselects all atoms that belong to a protein, but are not in a lysine or alanine residue
Geometric
- around distance selection
- selects all atoms a certain cutoff away from another selection,
e.g.
around 3.5 proteinselects all atoms not belonging to protein that are within 3.5 Angstroms from the protein - point x y z distance
- selects all atoms within a cutoff of a point in space, make sure
coordinate is separated by spaces,
e.g.
point 5.0 5.0 5.0 3.5selects all atoms within 3.5 Angstroms of the coordinate (5.0, 5.0, 5.0) - prop [abs] property operator value
- selects atoms based on position, using property x, y,
or z coordinate. Supports the abs keyword (for absolute
value) and the following operators: <, >, <=, >=, ==, !=.
For example,
prop z >= 5.0selects all atoms with z coordinate greater than 5.0;prop abs z <= 5.0selects all atoms within -5.0 <= z <= 5.0. - sphzone radius selection
- Selects all atoms that are within radius of the center of geometry of selection
- sphlayer inner radius outer radius selection
- Similar to sphzone, but also excludes atoms that are within inner radius of the selection COG
- cyzone externalRadius zMax zMin selection
- selects all atoms within a cylindric zone centered in the
center of geometry (COG) of a given selection,
e.g.
cyzone 15 4 -8 protein and resid 42selects the center of geometry of protein and resid 42, and creates a cylinder of external radius 15 centered on the COG. In z, the cylinder extends from 4 above the COG to 8 below. Positive values for zMin, or negative ones for zMax, are allowed. - cylayer innerRadius externalRadius zMax zMin selection
- selects all atoms within a cylindric layer centered in the
center of geometry (COG) of a given selection,
e.g.
cylayer 5 10 10 -8 proteinselects the center of geometry of protein, and creates a cylindrical layer of inner radius 5, external radius 10 centered on the COG. In z, the cylinder extends from 10 above the COG to 8 below. Positive values for zMin, or negative ones for zMax, are allowed.
Connectivity
- byres selection
- selects all atoms that are in the same segment and residue as selection, e.g. specify the subselection after the byres keyword
- bonded selection
- selects all atoms that are bonded to selection
eg:
select name H and bonded name Oselects only hydrogens bonded to oxygens
Index
- bynum index-range
- selects all atoms within a range of (1-based) inclusive indices,
e.g.
bynum 1selects the first atom in the universe;bynum 5:10selects atoms 5 through 10 inclusive. All atoms in theUniverseare consecutively numbered, and the index runs from 1 up to the total number of atoms. - index index-range
- selects all atoms within a range of (0-based) inclusive indices,
e.g.
index 0selects the first atom in the universe;index 5:10selects atoms 6 through 11 inclusive. All atoms in theUniverseare consecutively numbered, and the index runs from 0 up to the total number of atoms - 1.
Preexisting selections
- group group-name
- selects the atoms in the
AtomGrouppassed to the function as a keyword argument named group-name. Only the atoms common to group-name and the instanceselect_atoms()was called from will be considered, unlessgroupis preceded by theglobalkeyword. group-name will be included in the parsing just by comparison of atom indices. This means that it is up to the user to make sure the group-name group was defined in an appropriateUniverse. - global selection
- by default, when issuing
select_atoms()from anAtomGroup, selections and subselections are returned intersected with the atoms of that instance. Prefixing a selection term withglobalcauses its selection to be returned in its entirety. As an example, theglobalkeyword allows forlipids.select_atoms("around 10 global protein")— wherelipidsis a group that does not contain any proteins. Wereglobalabsent, the result would be an empty selection since theproteinsubselection would itself be empty. When issuingselect_atoms()from aUniverse,globalis ignored.
- Dynamic selections
- If
select_atoms()is invoked with named argument updating set to True, anUpdatingAtomGroupinstance will be returned, instead of a regularAtomGroup. It behaves just like the latter, with the difference that the selection expressions are re-evaluated every time the trajectory frame changes (this happens lazily, only when theUpdatingAtomGroupis accessed so that there is no redundant updating going on). Issuing an updating selection from an already updating group will cause later updates to also reflect the updating of the base group. A non-updating selection or a slicing operation made on anUpdatingAtomGroupwill return a staticAtomGroup, which will no longer update across frames.
Changed in version 0.7.4: Added resnum selection.
Changed in version 0.8.1: Added group and fullgroup selections.
Changed in version 0.13.0: Added bonded selection.
Changed in version 0.16.0: Resid selection now takes icodes into account where present.
Changed in version 0.16.0: Updating selections now possible by setting the updating argument.
Changed in version 0.17.0: Added moltype and molnum selections.
Changed in version 0.19.0: Added strict type checking for passed groups. Added periodic kwarg (default True)
Changed in version 0.19.2: Empty sel string now returns an empty Atom group.
Changed in version 1.0.0: The
fullgroupselection has now been removed in favor of the equivalentglobal groupselection. Removed flags affecting default behaviour for periodic selections; periodic are now on by default (as with default flags)
-
split(level)[source]¶ Split
AtomGroupinto alistofAtomGroupsby level.Parameters: level ({'atom', 'residue', 'molecule', 'segment'}) – New in version 0.9.0.
Changed in version 0.17.0: Added the ‘molecule’ level.
-
subtract(other)¶ Group with elements from this Group that don’t appear in other
The original order of this group is kept, as well as any duplicate elements. If an element of this Group is duplicated and appears in the other Group or Component, then all the occurences of that element are removed from the returned Group.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the elements of self that are not in other, conserves order and duplicates. Return type: Group Example
Unlike
difference()this method will not sort or remove duplicates.>>> ag1 = u.atoms[[3, 3, 2, 2, 1, 1]] >>> ag2 = u.atoms[2] >>> ag3 = ag1 - ag2 # or ag1.subtract(ag2) >>> ag1.indices array([3, 3, 1, 1])
See also
New in version 0.16.
-
symmetric_difference(other)¶ Group of elements which are only in one of this Group or another
This method removes duplicate elements and the result is sorted. It is synomym to the ^ operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the elements that are in self or in other but not in both, without duplicate elements Return type: Group Example
>>> ag1 = u.atoms[[0, 1, 5, 3, 3, 2]] >>> ag2 = u.atoms[[4, 4, 6, 2, 3, 5]] >>> ag3 = ag1 ^ ag2 # or ag1.symmetric_difference(ag2) >>> ag3.indices # 0 and 1 are only in ag1, 4 and 6 are only in ag2 [0, 1, 4, 6]
See also
New in version 0.16.
-
transform(M)¶ Apply homogenous transformation matrix M to the coordinates.
Atomcoordinates are rotated and translated in-place.Parameters: M (array_like) – 4x4 matrix with the rotation in R = M[:3, :3]and the translation int = M[:3, 3].Returns: Return type: self See also
MDAnalysis.lib.transformations()- module of all coordinate transforms
Notes
The rotation \(\mathsf{R}\) is about the origin and is applied before the translation \(\mathbf{t}\):
\[\mathbf{x}' = \mathsf{R}\mathbf{x} + \mathbf{t}\]
-
translate(t)¶ Apply translation vector t to the selection’s coordinates.
Atomcoordinates are translated in-place.Parameters: t (array_like) – vector to translate coordinates with Returns: Return type: self See also
MDAnalysis.lib.transformations()- module of all coordinate transforms
Notes
The method applies a translation to the
AtomGroupfrom current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\):\[\mathbf{x}' = \mathbf{x} + \mathbf{t}\]
-
ts¶ Temporary Timestep that contains the selection coordinates.
A
Timestepinstance, which can be passed to a trajectory writer.If
tsis modified then these modifications will be present until the frame number changes (which typically happens when the underlyingtrajectoryframe changes).It is not possible to assign a new
Timestepto theAtomGroup.tsattribute; change attributes of the object.
-
union(other)¶ Group of elements either in this Group or another
On the contrary to concatenation, this method sort the elements and removes duplicate ones. It is synomymous to the | operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the combined elements of self and other, without duplicate elements Return type: Group Example
In contrast to
concatenate(), any duplicates are dropped and the result is sorted.>>> ag1 = u.select_atoms('name O') >>> ag2 = u.select_atoms('name N') >>> ag3 = ag1 | ag2 # or ag1.union(ag2) >>> ag3[:3].names array(['N', 'O', 'N'], dtype=object)
See also
New in version 0.16.
-
unique¶ An
AtomGroupcontaining sorted and uniqueAtomsonly.If the
AtomGroupis unique, this is the group itself.Examples
>>> ag = u.atoms[[2, 1, 2, 2, 1, 0]] >>> ag <AtomGroup with 6 atoms> >>> ag.ix array([2, 1, 2, 2, 1, 0]) >>> ag2 = ag.unique >>> ag2 <AtomGroup with 3 atoms> >>> ag2.ix array([0, 1, 2]) >>> ag2.unique is ag2 True
New in version 0.16.0.
Changed in version 0.19.0: If the
AtomGroupis already unique,AtomGroup.uniquenow returns the group itself instead of a copy.
-
unwrap(compound='fragments', reference='com', inplace=True)¶ Move atoms of this group so that bonds within the group’s compounds aren’t split across periodic boundaries.
This function is most useful when atoms have been packed into the primary unit cell, causing breaks mid-molecule, with the molecule then appearing on either side of the unit cell. This is problematic for operations such as calculating the center of mass of the molecule.
+-----------+ +-----------+ | | | | | 6 3 | | 3 | 6 | ! ! | | ! | ! |-5-8 1-2-| ==> | 1-2-|-5-8 | ! ! | | ! | ! | 7 4 | | 4 | 7 | | | | +-----------+ +-----------+
Parameters: - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to unwrap. Note that, in any case, all atoms within each compound must be interconnected by bonds, i.e., compounds must correspond to (parts of) molecules.
- reference ({'com', 'cog', None}, optional) – If
'com'(center of mass) or'cog'(center of geometry), the unwrapped compounds will be shifted so that their individual reference point lies within the primary unit cell. IfNone, no such shift is performed. - inplace (bool, optional) – If
True, coordinates are modified in place.
Returns: coords – Unwrapped atom coordinate array of shape
(n, 3).Return type: Raises: NoDataError– If compound is'molecules'but the underlying topology does not contain molecule information, or if reference is'com'but the topology does not contain masses.ValueError– If reference is not one of'com','cog', orNone, or if reference is'com'and the total mass of any compound is zero.
Note
Be aware of the fact that only atoms belonging to the group will be unwrapped! If you want entire molecules to be unwrapped, make sure that all atoms of these molecules are part of the group.
An AtomGroup containing all atoms of all fragments in the group
agcan be created with:all_frag_atoms = sum(ag.fragments)
See also
make_whole(),wrap(),pack_into_box(),apply_PBC()New in version 0.20.0.
-
ureybradley¶ This
AtomGrouprepresented as anMDAnalysis.core.topologyobjects.UreyBradleyobjectRaises: ValueError– If theAtomGroupis not length 2New in version 1.0.0.
-
velocities¶ Velocities of the
Atomsin theAtomGroup.A
numpy.ndarraywithshape=(n_atoms, 3)anddtype=numpy.float32.The velocities can be changed by assigning an array of the appropriate shape, i.e. either
(n_atoms, 3)to assign individual velocities or(3,)to assign the same velocity to allAtoms(e.g.ag.velocities = array([0,0,0])will give allAtomszerovelocity).Raises: NoDataError– If the underlyingTimestepdoes not containvelocities.
-
wrap(compound='atoms', center='com', box=None, inplace=True)¶ Shift the contents of this group back into the primary unit cell according to periodic boundary conditions.
Specifying a compound will keep the
Atomsin each compound together during the process. If compound is different from'atoms', each compound as a whole will be shifted so that its center lies within the primary unit cell.Parameters: - compound ({'atoms', 'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during wrapping. Note that,
in any case, only the positions of
Atomsbelonging to the group will be taken into account. - center ({'com', 'cog'}) – How to define the center of a given group of atoms. If compound is
'atoms', this parameter is meaningless and therefore ignored. - box (array_like, optional) –
The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by
MDAnalysis.coordinates.base.Timestep.dimensions:[lx, ly, lz, alpha, beta, gamma].If
None, uses the dimensions of the current time step. - inplace (bool, optional) – If
True, coordinates will be changed in place.
Returns: Array of wrapped atom coordinates of dtype np.float32 and shape
(len(self.atoms.n_atoms), 3)Return type: Raises: ValueError– If compound is not one of'atoms','group','segments','residues','molecules', or'fragments'.NoDataError– If compound is'molecule'but the topology doesn’t contain molecule information (molnums) or if compound is'fragments'but the topology doesn’t contain bonds or if center is'com'but the topology doesn’t contain masses.
Notes
All atoms of the group will be moved so that the centers of its compounds lie within the primary periodic image. For orthorhombic unit cells, the primary periodic image is defined as the half-open interval \([0,L_i)\) between \(0\) and boxlength \(L_i\) in all dimensions \(i\in\{x,y,z\}\), i.e., the origin of the of the simulation box is taken to be at the origin \((0,0,0)\) of the euclidian coordinate system. A compound center residing at position \(x_i\) in dimension \(i\) will be shifted to \(x_i'\) according to
\[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\,.\]When specifying a compound, the translation is calculated based on each compound. The same translation is applied to all atoms within this compound, meaning it will not be broken by the shift. This might however mean that not all atoms of a compound will be inside the unit cell after wrapping, but rather will be the center of the compound.
Be aware of the fact that only atoms belonging to the group will be taken into account!
center allows to define how the center of each group is computed. This can be either
'com'for center of mass, or'cog'for center of geometry.box allows a unit cell to be given for the transformation. If not specified, the
dimensionsinformation from the currentTimestepwill be used.Note
AtomGroup.wrap()is currently faster thanResidueGroup.wrap()orSegmentGroup.wrap().See also
pack_into_box(),unwrap(),MDanalysis.lib.distances.apply_PBC()New in version 0.9.2.
Changed in version 0.20.0: The method only acts on atoms belonging to the group and returns the wrapped positions as a
numpy.ndarray. Added optional argument inplace.- compound ({'atoms', 'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during wrapping. Note that,
in any case, only the positions of
-
write(filename=None, file_format=None, filenamefmt='{trjname}_{frame}', frames=None, **kwargs)[source]¶ Write AtomGroup to a file.
The output can either be a coordinate file or a selection, depending on the format.
Examples
>>> ag = u.atoms >>> ag.write('selection.ndx') # Write a gromacs index file >>> ag.write('coordinates.pdb') # Write the current frame as PDB >>> # Write the trajectory in XTC format >>> ag.write('trajectory.xtc', frames='all') >>> # Write every other frame of the trajectory in PBD format >>> ag.write('trajectory.pdb', frames=u.trajectory[::2])
Parameters: - filename (str, optional) –
None: create TRJNAME_FRAME.FORMAT from filenamefmt [None] - file_format (str, optional) – The name or extension of a coordinate, trajectory, or selection file format such as PDB, CRD, GRO, VMD (tcl), PyMol (pml), Gromacs (ndx) CHARMM (str) or Jmol (spt); case-insensitive [PDB]
- filenamefmt (str, optional) – format string for default filename; use substitution tokens ‘trjname’ and ‘frame’ [“%(trjname)s_%(frame)d”]
- bonds (str, optional) – how to handle bond information, especially relevant for PDBs.
"conect": write only the CONECT records defined in the original file."all": write out all bonds, both the original defined and those guessed by MDAnalysis.None: do not write out bonds. Default is"conect". - frames (array-like or slice or FrameIteratorBase or str, optional) – An ensemble of frames to write. The ensemble can be an list or
array of frame indices, a mask of booleans, an instance of
slice, or the value returned when a trajectory is indexed. By default, frames is set toNoneand only the current frame is written. If frames is set to “all”, then all the frame from trajectory are written.
Changed in version 0.9.0: Merged with write_selection. This method can now write both selections out.
Changed in version 0.19.0: Can write multiframe trajectories with the ‘frames’ argument.
- filename (str, optional) –
-
class
MDAnalysis.core.groups.ResidueGroup(*args)[source]¶ ResidueGroup base class.
This class is used by a
Universefor generating its Topology-specificResidueGroupclass. All theTopologyAttrcomponents are obtained fromGroupBase, so this class only includes ad-hoc methods specific toResidueGroups.ResidueGroups can be compared and combined using group operators. See the list of these operators on
GroupBase.Deprecated since version 0.16.2: Instant selectors of Segments will be removed in the 1.0 release.
Changed in version 1.0.0: Removed instant selectors, use select_atoms instead
-
accumulate(attribute, function=<function sum>, compound='group')¶ Accumulates the attribute associated with (compounds of) the group.
Accumulates the attribute of
Atomsin the group. The accumulation perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly. By default, the method sums up all attributes per compound, but any function that takes an array and returns an acuumulation over a given axis can be used. For multi-dimensional input arrays, the accumulation is performed along the first axis.Parameters: - attribute (str or array_like) – Attribute or array of values to accumulate.
If a
numpy.ndarray(or compatible) is provided, its first dimension must have the same length as the total number of atoms in the group. - function (callable, optional) – The function performing the accumulation. It must take the array of
attribute values to accumulate as its only positional argument and
accept an (optional) keyword argument
axisallowing to specify the axis along which the accumulation is performed. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the accumulation of all attributes associated with atoms in the group will be returned as a single value. Otherwise, the accumulation of the attributes perSegment,Residue, molecule, or fragment will be returned as a 1d array. Note that, in any case, only theAtomsbelonging to the group will be taken into account.
Returns: Acuumulation of the attribute. If compound is set to
'group', the first dimension of the attribute array will be contracted to a single value. If compound is set to'segments','residues','molecules', or'fragments', the length of the first dimension will correspond to the number of compounds. In all cases, the other dimensions of the returned array will be of the original shape (without the first dimension).Return type: Raises: ValueError– If the length of a provided attribute array does not correspond to the number of atoms in the group.ValueError– If compound is not one of'group','segments','residues','molecules', or'fragments'.NoDataError– If compound is'molecule'but the topology doesn’t contain molecule information (molnums), or if compound is'fragments'but the topology doesn’t contain bonds.
Examples
To find the total charge of a given
AtomGroup:>>> sel = u.select_atoms('prop mass > 4.0') >>> sel.accumulate('charges')
To find the total mass per residue of all CA
Atoms:>>> sel = u.select_atoms('name CA') >>> sel.accumulate('masses', compound='residues')
To find the maximum atomic charge per fragment of a given
AtomGroup:>>> sel.accumulate('charges', compound="fragments", function=np.max)
New in version 0.20.0.
- attribute (str or array_like) – Attribute or array of values to accumulate.
If a
-
atoms¶ An
AtomGroupofAtomspresent in thisResidueGroup.The
Atomsare ordered locally byResiduein theResidueGroup. Duplicates are not removed.
-
bbox(pbc=False)¶ Return the bounding box of the selection.
The lengths A,B,C of the orthorhombic enclosing box are
L = AtomGroup.bbox() A,B,C = L[1] - L[0]
Parameters: pbc (bool, optional) – If True, move allAtomsto the primary unit cell before calculation. [False]Returns: corners – 2x3 array giving corners of bounding box as [[xmin, ymin, zmin], [xmax, ymax, zmax]].Return type: numpy.ndarray New in version 0.7.2.
Changed in version 0.8: Added pbc keyword
Changed in version 1.0.0: Removed flags affecting default behaviour
-
bsphere(pbc=False)¶ Return the bounding sphere of the selection.
The sphere is calculated relative to the
center of geometry.Parameters: pbc (bool, optional) – If True, move all atoms to the primary unit cell before calculation. [False]Returns: - R (float) – Radius of the bounding sphere.
- center (numpy.ndarray) – Coordinates of the sphere center as
[xcen, ycen, zcen].
New in version 0.7.3.
Changed in version 0.8: Added pbc keyword
-
center(weights, pbc=False, compound='group', unwrap=False)¶ Weighted center of (compounds of) the group
Computes the weighted center of
Atomsin the group. Weighted centers perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the weights of a compound sum up to zero, the coordinates of that compound’s weighted center will benan(not a number).Parameters: - weights (array_like or None) – Weights to be used. Setting weights=None is equivalent to passing identical weights for all atoms of the group.
- pbc (bool, optional) – If
Trueand compound is'group', move all atoms to the primary unit cell before calculation. IfTrueand compound is'segments','residues','molecules', or'fragments', the center of each compound will be calculated without moving anyAtomsto keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default [False]. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the weighted center of all atoms in the group will be returned as a single position vector. Else, the weighted centers of eachSegment,Residue, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions ofAtomsbelonging to the group will be taken into account. - unwrap (bool, optional) – If
True, compounds will be unwrapped before computing their centers.
Returns: center – Position vector(s) of the weighted center(s) of the group. If compound was set to
'group', the output will be a single position vector. If compound was set to'segments','residues','molecules', or'fragments', the output will be a 2d array of shape(n, 3)wherenis the number of compounds.Return type: Raises: ValueError– If compound is not one of'group','segments','residues','molecules', or'fragments'.ValueError– If both ‘pbc’ and ‘unwrap’ set to true.NoDataError– If compound is'molecule'but the topology doesn’t contain molecule information (molnums) or if compound is'fragments'but the topology doesn’t contain bonds.
Examples
To find the center of charge of a given
AtomGroup:>>> sel = u.select_atoms('prop mass > 4.0') >>> sel.center(sel.charges)
To find the centers of mass per residue of all CA
Atoms:>>> sel = u.select_atoms('name CA') >>> sel.center(sel.masses, compound='residues')
Changed in version 0.19.0: Added compound parameter
Changed in version 0.20.0: Added
'molecules'and'fragments'compoundsChanged in version 0.20.0: Added unwrap parameter
Changed in version 1.0.0: Removed flags affecting default behaviour
-
center_of_geometry(pbc=False, compound='group', unwrap=False)¶ Center of geometry of (compounds of) the group.
Computes the center of geometry (a.k.a. centroid) of
Atomsin the group. Centers of geometry perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly.Parameters: - pbc (bool, optional) – If
Trueand compound is'group', move all atoms to the primary unit cell before calculation. IfTrueand compound is'segments'or'residues', the center of each compound will be calculated without moving anyAtomsto keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the center of geometry of allAtomsin the group will be returned as a single position vector. Else, the centers of geometry of eachSegmentorResiduewill be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions ofAtomsbelonging to the group will be taken into account. - unwrap (bool, optional) – If
True, compounds will be unwrapped before computing their centers.
Returns: center – Position vector(s) of the geometric center(s) of the group. If compound was set to
'group', the output will be a single position vector. If compound was set to'segments'or'residues', the output will be a 2d array of shape(n, 3)wherenis the number of compounds.Return type: Changed in version 0.8: Added pbc keyword
Changed in version 0.19.0: Added compound parameter
Changed in version 0.20.0: Added
'molecules'and'fragments'compoundsChanged in version 0.20.0: Added unwrap parameter
Changed in version 1.0.0: Removed flags affecting default behaviour
- pbc (bool, optional) – If
-
centroid(pbc=False, compound='group', unwrap=False)¶ Center of geometry of (compounds of) the group.
Computes the center of geometry (a.k.a. centroid) of
Atomsin the group. Centers of geometry perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly.Parameters: - pbc (bool, optional) – If
Trueand compound is'group', move all atoms to the primary unit cell before calculation. IfTrueand compound is'segments'or'residues', the center of each compound will be calculated without moving anyAtomsto keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the center of geometry of allAtomsin the group will be returned as a single position vector. Else, the centers of geometry of eachSegmentorResiduewill be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions ofAtomsbelonging to the group will be taken into account. - unwrap (bool, optional) – If
True, compounds will be unwrapped before computing their centers.
Returns: center – Position vector(s) of the geometric center(s) of the group. If compound was set to
'group', the output will be a single position vector. If compound was set to'segments'or'residues', the output will be a 2d array of shape(n, 3)wherenis the number of compounds.Return type: Changed in version 0.8: Added pbc keyword
Changed in version 0.19.0: Added compound parameter
Changed in version 0.20.0: Added
'molecules'and'fragments'compoundsChanged in version 0.20.0: Added unwrap parameter
Changed in version 1.0.0: Removed flags affecting default behaviour
- pbc (bool, optional) – If
-
concatenate(other)¶ Concatenate with another Group or Component of the same level.
Duplicate entries and original order is preserved. It is synomymous to the + operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with elements of self and other concatenated Return type: Group Example
The order of the original contents (including duplicates) are preserved when performing a concatenation.
>>> ag1 = u.select_atoms('name O') >>> ag2 = u.select_atoms('name N') >>> ag3 = ag1 + ag2 # or ag1.concatenate(ag2) >>> ag3[:3].names array(['O', 'O', 'O'], dtype=object) >>> ag3[-3:].names array(['N', 'N', 'N'], dtype=object)
New in version 0.16.0.
-
copy()¶ Get another group identical to this one.
New in version 0.19.0.
-
difference(other)¶ Elements from this Group that do not appear in another
This method removes duplicate elements and sorts the result. As such, it is different from
subtract().difference()is synomymous to the - operator.Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the elements of self that are not in other, without duplicate elements Return type: Group See also
New in version 0.16.
-
dimensions¶ Obtain a copy of the dimensions of the currently loaded Timestep
-
groupby(topattrs)¶ Group together items in this group according to values of topattr
Parameters: topattrs (str or list) – One or more topology attributes to group components by. Single arguments are passed as a string. Multiple arguments are passed as a list. Returns: Unique values of the multiple combinations of topology attributes as keys, Groups as values. Return type: dict Example
To group atoms with the same mass together:
>>> ag.groupby('masses') {12.010999999999999: <AtomGroup with 462 atoms>, 14.007: <AtomGroup with 116 atoms>, 15.999000000000001: <AtomGroup with 134 atoms>}
To group atoms with the same residue name and mass together:
>>> ag.groupby(['resnames', 'masses']) {('ALA', 1.008): <AtomGroup with 95 atoms>, ('ALA', 12.011): <AtomGroup with 57 atoms>, ('ALA', 14.007): <AtomGroup with 19 atoms>, ('ALA', 15.999): <AtomGroup with 19 atoms>}, ('ARG', 1.008): <AtomGroup with 169 atoms>, ...}
>>> ag.groupby(['resnames', 'masses'])('ALA', 15.999) <AtomGroup with 19 atoms>
New in version 0.16.0.
Changed in version 0.18.0: The function accepts multiple attributes
-
intersection(other)¶ Group of elements which are in both this Group and another
This method removes duplicate elements and sorts the result. It is synomymous to the & operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the common elements of self and other, without duplicate elements Return type: Group Example
Intersections can be used when the select atoms string would become too complicated. For example to find the water atoms which are within 4.0A of two segments:
>>> shell1 = u.select_atoms('resname SOL and around 4.0 segid 1') >>> shell2 = u.select_atoms('resname SOL and around 4.0 segid 2') >>> common = shell1 & shell2 # or shell1.intersection(shell2)
See also
New in version 0.16.
-
is_strict_subset(other)¶ If this Group is a subset of another Group but not identical
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a strict subset of the other oneReturn type: bool New in version 0.16.
-
is_strict_superset(other)¶ If this Group is a superset of another Group but not identical
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a strict superset of the other oneReturn type: bool New in version 0.16.
-
isdisjoint(other)¶ If the Group has no elements in common with the other Group
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif the two Groups do not have common elementsReturn type: bool New in version 0.16.
-
issubset(other)¶ If all elements of this Group are part of another Group
Note that an empty group is a subset of any group of the same level.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a subset of the other oneReturn type: bool New in version 0.16.
-
issuperset(other)¶ If all elements of another Group are part of this Group
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a subset of the other oneReturn type: bool New in version 0.16.
-
isunique¶ Boolean indicating whether all components of the group are unique, i.e., the group contains no duplicates.
Examples
>>> ag = u.atoms[[2, 1, 2, 2, 1, 0]] >>> ag <AtomGroup with 6 atoms> >>> ag.isunique False >>> ag2 = ag.unique >>> ag2 <AtomGroup with 3 atoms> >>> ag2.isunique True
New in version 0.19.0.
-
ix¶ Unique indices of the components in the Group.
- If this Group is an
AtomGroup, these are the indices of theAtominstances. - If it is a
ResidueGroup, these are the indices of theResidueinstances. - If it is a
SegmentGroup, these are the indices of theSegmentinstances.
- If this Group is an
-
ix_array¶ Unique indices of the components in the Group.
For a Group,
ix_arrayis the same asix. This method gives a consistent API between components and groups.See also
-
n_atoms¶ Number of
Atomspresent in thisResidueGroup, including duplicate residues (and thus, duplicate atoms).Equivalent to
len(self.atoms).
-
n_residues¶ Number of residues in the
ResidueGroup.Equivalent to
len(self).
-
n_segments¶ Number of unique segments present in the ResidueGroup.
Equivalent to
len(self.segments).
-
pack_into_box(box=None, inplace=True)¶ Shift all
Atomsin this group to the primary unit cell.Parameters: - box (array_like) – Box dimensions, can be either orthogonal or triclinic information.
Cell dimensions must be in an identical to format to those returned
by
MDAnalysis.coordinates.base.Timestep.dimensions,[lx, ly, lz, alpha, beta, gamma]. IfNone, uses these timestep dimensions. - inplace (bool) –
Trueto change coordinates in place.
Returns: coords – Shifted atom coordinates.
Return type: Notes
All atoms will be moved so that they lie between 0 and boxlength \(L_i\) in all dimensions, i.e. the lower left corner of the simulation box is taken to be at (0,0,0):
\[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\]The default is to take unit cell information from the underlying
Timestepinstance. The optional argument box can be used to provide alternative unit cell information (in the MDAnalysis standard format[Lx, Ly, Lz, alpha, beta, gamma]).Works with either orthogonal or triclinic box types.
Note
pack_into_box()is identical towrap()with all default keywords.Note
AtomGroup.pack_into_box()is currently faster thanResidueGroup.pack_into_box()orSegmentGroup.pack_into_box().New in version 0.8.
- box (array_like) – Box dimensions, can be either orthogonal or triclinic information.
Cell dimensions must be in an identical to format to those returned
by
-
residues¶ The
ResidueGroupitself.See also
copy- return a true copy of the
ResidueGroup
Changed in version 0.19.0: In previous versions, this returned a copy, but now the
ResidueGroupitself is returned. This should not affect any code but only speed up calculations.
-
rotate(R, point=(0, 0, 0))¶ Apply a rotation matrix R to the selection’s coordinates. \(\mathsf{R}\) is a 3x3 orthogonal matrix that transforms a vector \(\mathbf{x} \rightarrow \mathbf{x}'\):
\[\mathbf{x}' = \mathsf{R}\mathbf{x}\]Atomcoordinates are rotated in-place.Parameters: - R (array_like) – 3x3 rotation matrix
- point (array_like, optional) – Center of rotation
Returns: Return type: self
Notes
By default, rotates about the origin
point=(0, 0, 0). To rotate a groupgaround its center of geometry, useg.rotate(R, point=g.center_of_geometry()).See also
rotateby()- rotate around given axis and angle
MDAnalysis.lib.transformations()- module of all coordinate transforms
-
rotateby(angle, axis, point=None)¶ Apply a rotation to the selection’s coordinates.
Parameters: - angle (float) – Rotation angle in degrees.
- axis (array_like) – Rotation axis vector.
- point (array_like, optional) – Center of rotation. If
Nonethen the center of geometry of this group is used.
Returns: Return type: self
Notes
The transformation from current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\) is
\[\mathbf{x}' = \mathsf{R}\,(\mathbf{x}-\mathbf{p}) + \mathbf{p}\]where \(\mathsf{R}\) is the rotation by angle around the axis going through point \(\mathbf{p}\).
See also
MDAnalysis.lib.transformations.rotation_matrix()calculate()- math:mathsf{R}
-
segments¶ Get sorted
SegmentGroupof the unique segments present in theResidueGroup.
-
subtract(other)¶ Group with elements from this Group that don’t appear in other
The original order of this group is kept, as well as any duplicate elements. If an element of this Group is duplicated and appears in the other Group or Component, then all the occurences of that element are removed from the returned Group.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the elements of self that are not in other, conserves order and duplicates. Return type: Group Example
Unlike
difference()this method will not sort or remove duplicates.>>> ag1 = u.atoms[[3, 3, 2, 2, 1, 1]] >>> ag2 = u.atoms[2] >>> ag3 = ag1 - ag2 # or ag1.subtract(ag2) >>> ag1.indices array([3, 3, 1, 1])
See also
New in version 0.16.
-
symmetric_difference(other)¶ Group of elements which are only in one of this Group or another
This method removes duplicate elements and the result is sorted. It is synomym to the ^ operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the elements that are in self or in other but not in both, without duplicate elements Return type: Group Example
>>> ag1 = u.atoms[[0, 1, 5, 3, 3, 2]] >>> ag2 = u.atoms[[4, 4, 6, 2, 3, 5]] >>> ag3 = ag1 ^ ag2 # or ag1.symmetric_difference(ag2) >>> ag3.indices # 0 and 1 are only in ag1, 4 and 6 are only in ag2 [0, 1, 4, 6]
See also
New in version 0.16.
-
transform(M)¶ Apply homogenous transformation matrix M to the coordinates.
Atomcoordinates are rotated and translated in-place.Parameters: M (array_like) – 4x4 matrix with the rotation in R = M[:3, :3]and the translation int = M[:3, 3].Returns: Return type: self See also
MDAnalysis.lib.transformations()- module of all coordinate transforms
Notes
The rotation \(\mathsf{R}\) is about the origin and is applied before the translation \(\mathbf{t}\):
\[\mathbf{x}' = \mathsf{R}\mathbf{x} + \mathbf{t}\]
-
translate(t)¶ Apply translation vector t to the selection’s coordinates.
Atomcoordinates are translated in-place.Parameters: t (array_like) – vector to translate coordinates with Returns: Return type: self See also
MDAnalysis.lib.transformations()- module of all coordinate transforms
Notes
The method applies a translation to the
AtomGroupfrom current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\):\[\mathbf{x}' = \mathbf{x} + \mathbf{t}\]
-
union(other)¶ Group of elements either in this Group or another
On the contrary to concatenation, this method sort the elements and removes duplicate ones. It is synomymous to the | operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the combined elements of self and other, without duplicate elements Return type: Group Example
In contrast to
concatenate(), any duplicates are dropped and the result is sorted.>>> ag1 = u.select_atoms('name O') >>> ag2 = u.select_atoms('name N') >>> ag3 = ag1 | ag2 # or ag1.union(ag2) >>> ag3[:3].names array(['N', 'O', 'N'], dtype=object)
See also
New in version 0.16.
-
unique¶ Return a
ResidueGroupcontaining sorted and uniqueResiduesonly.If the
ResidueGroupis unique, this is the group itself.Examples
>>> rg = u.residues[[2, 1, 2, 2, 1, 0]] >>> rg <ResidueGroup with 6 residues> >>> rg.ix array([2, 1, 2, 2, 1, 0]) >>> rg2 = rg.unique >>> rg2 <ResidueGroup with 3 residues> >>> rg2.ix array([0, 1, 2]) >>> rg2.unique is rg2 True
New in version 0.16.0.
Changed in version 0.19.0: If the
ResidueGroupis already unique,ResidueGroup.uniquenow returns the group itself instead of a copy.
-
unwrap(compound='fragments', reference='com', inplace=True)¶ Move atoms of this group so that bonds within the group’s compounds aren’t split across periodic boundaries.
This function is most useful when atoms have been packed into the primary unit cell, causing breaks mid-molecule, with the molecule then appearing on either side of the unit cell. This is problematic for operations such as calculating the center of mass of the molecule.
+-----------+ +-----------+ | | | | | 6 3 | | 3 | 6 | ! ! | | ! | ! |-5-8 1-2-| ==> | 1-2-|-5-8 | ! ! | | ! | ! | 7 4 | | 4 | 7 | | | | +-----------+ +-----------+
Parameters: - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to unwrap. Note that, in any case, all atoms within each compound must be interconnected by bonds, i.e., compounds must correspond to (parts of) molecules.
- reference ({'com', 'cog', None}, optional) – If
'com'(center of mass) or'cog'(center of geometry), the unwrapped compounds will be shifted so that their individual reference point lies within the primary unit cell. IfNone, no such shift is performed. - inplace (bool, optional) – If
True, coordinates are modified in place.
Returns: coords – Unwrapped atom coordinate array of shape
(n, 3).Return type: Raises: NoDataError– If compound is'molecules'but the underlying topology does not contain molecule information, or if reference is'com'but the topology does not contain masses.ValueError– If reference is not one of'com','cog', orNone, or if reference is'com'and the total mass of any compound is zero.
Note
Be aware of the fact that only atoms belonging to the group will be unwrapped! If you want entire molecules to be unwrapped, make sure that all atoms of these molecules are part of the group.
An AtomGroup containing all atoms of all fragments in the group
agcan be created with:all_frag_atoms = sum(ag.fragments)
See also
make_whole(),wrap(),pack_into_box(),apply_PBC()New in version 0.20.0.
-
wrap(compound='atoms', center='com', box=None, inplace=True)¶ Shift the contents of this group back into the primary unit cell according to periodic boundary conditions.
Specifying a compound will keep the
Atomsin each compound together during the process. If compound is different from'atoms', each compound as a whole will be shifted so that its center lies within the primary unit cell.Parameters: - compound ({'atoms', 'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during wrapping. Note that,
in any case, only the positions of
Atomsbelonging to the group will be taken into account. - center ({'com', 'cog'}) – How to define the center of a given group of atoms. If compound is
'atoms', this parameter is meaningless and therefore ignored. - box (array_like, optional) –
The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by
MDAnalysis.coordinates.base.Timestep.dimensions:[lx, ly, lz, alpha, beta, gamma].If
None, uses the dimensions of the current time step. - inplace (bool, optional) – If
True, coordinates will be changed in place.
Returns: Array of wrapped atom coordinates of dtype np.float32 and shape
(len(self.atoms.n_atoms), 3)Return type: Raises: ValueError– If compound is not one of'atoms','group','segments','residues','molecules', or'fragments'.NoDataError– If compound is'molecule'but the topology doesn’t contain molecule information (molnums) or if compound is'fragments'but the topology doesn’t contain bonds or if center is'com'but the topology doesn’t contain masses.
Notes
All atoms of the group will be moved so that the centers of its compounds lie within the primary periodic image. For orthorhombic unit cells, the primary periodic image is defined as the half-open interval \([0,L_i)\) between \(0\) and boxlength \(L_i\) in all dimensions \(i\in\{x,y,z\}\), i.e., the origin of the of the simulation box is taken to be at the origin \((0,0,0)\) of the euclidian coordinate system. A compound center residing at position \(x_i\) in dimension \(i\) will be shifted to \(x_i'\) according to
\[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\,.\]When specifying a compound, the translation is calculated based on each compound. The same translation is applied to all atoms within this compound, meaning it will not be broken by the shift. This might however mean that not all atoms of a compound will be inside the unit cell after wrapping, but rather will be the center of the compound.
Be aware of the fact that only atoms belonging to the group will be taken into account!
center allows to define how the center of each group is computed. This can be either
'com'for center of mass, or'cog'for center of geometry.box allows a unit cell to be given for the transformation. If not specified, the
dimensionsinformation from the currentTimestepwill be used.Note
AtomGroup.wrap()is currently faster thanResidueGroup.wrap()orSegmentGroup.wrap().See also
pack_into_box(),unwrap(),MDanalysis.lib.distances.apply_PBC()New in version 0.9.2.
Changed in version 0.20.0: The method only acts on atoms belonging to the group and returns the wrapped positions as a
numpy.ndarray. Added optional argument inplace.- compound ({'atoms', 'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during wrapping. Note that,
in any case, only the positions of
-
-
class
MDAnalysis.core.groups.SegmentGroup(*args)[source]¶ SegmentGroupbase class.This class is used by a
Universefor generating its Topology-specificSegmentGroupclass. All theTopologyAttrcomponents are obtained fromGroupBase, so this class only includes ad-hoc methods specific toSegmentGroups.SegmentGroupscan be compared and combined using group operators. See the list of these operators onGroupBase.Deprecated since version 0.16.2: Instant selectors of Segments will be removed in the 1.0 release.
Changed in version 1.0.0: Removed instant selectors, use select_atoms instead
-
accumulate(attribute, function=<function sum>, compound='group')¶ Accumulates the attribute associated with (compounds of) the group.
Accumulates the attribute of
Atomsin the group. The accumulation perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly. By default, the method sums up all attributes per compound, but any function that takes an array and returns an acuumulation over a given axis can be used. For multi-dimensional input arrays, the accumulation is performed along the first axis.Parameters: - attribute (str or array_like) – Attribute or array of values to accumulate.
If a
numpy.ndarray(or compatible) is provided, its first dimension must have the same length as the total number of atoms in the group. - function (callable, optional) – The function performing the accumulation. It must take the array of
attribute values to accumulate as its only positional argument and
accept an (optional) keyword argument
axisallowing to specify the axis along which the accumulation is performed. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the accumulation of all attributes associated with atoms in the group will be returned as a single value. Otherwise, the accumulation of the attributes perSegment,Residue, molecule, or fragment will be returned as a 1d array. Note that, in any case, only theAtomsbelonging to the group will be taken into account.
Returns: Acuumulation of the attribute. If compound is set to
'group', the first dimension of the attribute array will be contracted to a single value. If compound is set to'segments','residues','molecules', or'fragments', the length of the first dimension will correspond to the number of compounds. In all cases, the other dimensions of the returned array will be of the original shape (without the first dimension).Return type: Raises: ValueError– If the length of a provided attribute array does not correspond to the number of atoms in the group.ValueError– If compound is not one of'group','segments','residues','molecules', or'fragments'.NoDataError– If compound is'molecule'but the topology doesn’t contain molecule information (molnums), or if compound is'fragments'but the topology doesn’t contain bonds.
Examples
To find the total charge of a given
AtomGroup:>>> sel = u.select_atoms('prop mass > 4.0') >>> sel.accumulate('charges')
To find the total mass per residue of all CA
Atoms:>>> sel = u.select_atoms('name CA') >>> sel.accumulate('masses', compound='residues')
To find the maximum atomic charge per fragment of a given
AtomGroup:>>> sel.accumulate('charges', compound="fragments", function=np.max)
New in version 0.20.0.
- attribute (str or array_like) – Attribute or array of values to accumulate.
If a
-
atoms¶ An
AtomGroupofAtomspresent in thisSegmentGroup.The
Atomsare ordered locally byResidue, which are further ordered bySegmentin theSegmentGroup. Duplicates are not removed.
-
bbox(pbc=False)¶ Return the bounding box of the selection.
The lengths A,B,C of the orthorhombic enclosing box are
L = AtomGroup.bbox() A,B,C = L[1] - L[0]
Parameters: pbc (bool, optional) – If True, move allAtomsto the primary unit cell before calculation. [False]Returns: corners – 2x3 array giving corners of bounding box as [[xmin, ymin, zmin], [xmax, ymax, zmax]].Return type: numpy.ndarray New in version 0.7.2.
Changed in version 0.8: Added pbc keyword
Changed in version 1.0.0: Removed flags affecting default behaviour
-
bsphere(pbc=False)¶ Return the bounding sphere of the selection.
The sphere is calculated relative to the
center of geometry.Parameters: pbc (bool, optional) – If True, move all atoms to the primary unit cell before calculation. [False]Returns: - R (float) – Radius of the bounding sphere.
- center (numpy.ndarray) – Coordinates of the sphere center as
[xcen, ycen, zcen].
New in version 0.7.3.
Changed in version 0.8: Added pbc keyword
-
center(weights, pbc=False, compound='group', unwrap=False)¶ Weighted center of (compounds of) the group
Computes the weighted center of
Atomsin the group. Weighted centers perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the weights of a compound sum up to zero, the coordinates of that compound’s weighted center will benan(not a number).Parameters: - weights (array_like or None) – Weights to be used. Setting weights=None is equivalent to passing identical weights for all atoms of the group.
- pbc (bool, optional) – If
Trueand compound is'group', move all atoms to the primary unit cell before calculation. IfTrueand compound is'segments','residues','molecules', or'fragments', the center of each compound will be calculated without moving anyAtomsto keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default [False]. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the weighted center of all atoms in the group will be returned as a single position vector. Else, the weighted centers of eachSegment,Residue, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions ofAtomsbelonging to the group will be taken into account. - unwrap (bool, optional) – If
True, compounds will be unwrapped before computing their centers.
Returns: center – Position vector(s) of the weighted center(s) of the group. If compound was set to
'group', the output will be a single position vector. If compound was set to'segments','residues','molecules', or'fragments', the output will be a 2d array of shape(n, 3)wherenis the number of compounds.Return type: Raises: ValueError– If compound is not one of'group','segments','residues','molecules', or'fragments'.ValueError– If both ‘pbc’ and ‘unwrap’ set to true.NoDataError– If compound is'molecule'but the topology doesn’t contain molecule information (molnums) or if compound is'fragments'but the topology doesn’t contain bonds.
Examples
To find the center of charge of a given
AtomGroup:>>> sel = u.select_atoms('prop mass > 4.0') >>> sel.center(sel.charges)
To find the centers of mass per residue of all CA
Atoms:>>> sel = u.select_atoms('name CA') >>> sel.center(sel.masses, compound='residues')
Changed in version 0.19.0: Added compound parameter
Changed in version 0.20.0: Added
'molecules'and'fragments'compoundsChanged in version 0.20.0: Added unwrap parameter
Changed in version 1.0.0: Removed flags affecting default behaviour
-
center_of_geometry(pbc=False, compound='group', unwrap=False)¶ Center of geometry of (compounds of) the group.
Computes the center of geometry (a.k.a. centroid) of
Atomsin the group. Centers of geometry perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly.Parameters: - pbc (bool, optional) – If
Trueand compound is'group', move all atoms to the primary unit cell before calculation. IfTrueand compound is'segments'or'residues', the center of each compound will be calculated without moving anyAtomsto keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the center of geometry of allAtomsin the group will be returned as a single position vector. Else, the centers of geometry of eachSegmentorResiduewill be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions ofAtomsbelonging to the group will be taken into account. - unwrap (bool, optional) – If
True, compounds will be unwrapped before computing their centers.
Returns: center – Position vector(s) of the geometric center(s) of the group. If compound was set to
'group', the output will be a single position vector. If compound was set to'segments'or'residues', the output will be a 2d array of shape(n, 3)wherenis the number of compounds.Return type: Changed in version 0.8: Added pbc keyword
Changed in version 0.19.0: Added compound parameter
Changed in version 0.20.0: Added
'molecules'and'fragments'compoundsChanged in version 0.20.0: Added unwrap parameter
Changed in version 1.0.0: Removed flags affecting default behaviour
- pbc (bool, optional) – If
-
centroid(pbc=False, compound='group', unwrap=False)¶ Center of geometry of (compounds of) the group.
Computes the center of geometry (a.k.a. centroid) of
Atomsin the group. Centers of geometry perResidue,Segment, molecule, or fragment can be obtained by setting the compound parameter accordingly.Parameters: - pbc (bool, optional) – If
Trueand compound is'group', move all atoms to the primary unit cell before calculation. IfTrueand compound is'segments'or'residues', the center of each compound will be calculated without moving anyAtomsto keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False. - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If
'group', the center of geometry of allAtomsin the group will be returned as a single position vector. Else, the centers of geometry of eachSegmentorResiduewill be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions ofAtomsbelonging to the group will be taken into account. - unwrap (bool, optional) – If
True, compounds will be unwrapped before computing their centers.
Returns: center – Position vector(s) of the geometric center(s) of the group. If compound was set to
'group', the output will be a single position vector. If compound was set to'segments'or'residues', the output will be a 2d array of shape(n, 3)wherenis the number of compounds.Return type: Changed in version 0.8: Added pbc keyword
Changed in version 0.19.0: Added compound parameter
Changed in version 0.20.0: Added
'molecules'and'fragments'compoundsChanged in version 0.20.0: Added unwrap parameter
Changed in version 1.0.0: Removed flags affecting default behaviour
- pbc (bool, optional) – If
-
concatenate(other)¶ Concatenate with another Group or Component of the same level.
Duplicate entries and original order is preserved. It is synomymous to the + operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with elements of self and other concatenated Return type: Group Example
The order of the original contents (including duplicates) are preserved when performing a concatenation.
>>> ag1 = u.select_atoms('name O') >>> ag2 = u.select_atoms('name N') >>> ag3 = ag1 + ag2 # or ag1.concatenate(ag2) >>> ag3[:3].names array(['O', 'O', 'O'], dtype=object) >>> ag3[-3:].names array(['N', 'N', 'N'], dtype=object)
New in version 0.16.0.
-
copy()¶ Get another group identical to this one.
New in version 0.19.0.
-
difference(other)¶ Elements from this Group that do not appear in another
This method removes duplicate elements and sorts the result. As such, it is different from
subtract().difference()is synomymous to the - operator.Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the elements of self that are not in other, without duplicate elements Return type: Group See also
New in version 0.16.
-
dimensions¶ Obtain a copy of the dimensions of the currently loaded Timestep
-
groupby(topattrs)¶ Group together items in this group according to values of topattr
Parameters: topattrs (str or list) – One or more topology attributes to group components by. Single arguments are passed as a string. Multiple arguments are passed as a list. Returns: Unique values of the multiple combinations of topology attributes as keys, Groups as values. Return type: dict Example
To group atoms with the same mass together:
>>> ag.groupby('masses') {12.010999999999999: <AtomGroup with 462 atoms>, 14.007: <AtomGroup with 116 atoms>, 15.999000000000001: <AtomGroup with 134 atoms>}
To group atoms with the same residue name and mass together:
>>> ag.groupby(['resnames', 'masses']) {('ALA', 1.008): <AtomGroup with 95 atoms>, ('ALA', 12.011): <AtomGroup with 57 atoms>, ('ALA', 14.007): <AtomGroup with 19 atoms>, ('ALA', 15.999): <AtomGroup with 19 atoms>}, ('ARG', 1.008): <AtomGroup with 169 atoms>, ...}
>>> ag.groupby(['resnames', 'masses'])('ALA', 15.999) <AtomGroup with 19 atoms>
New in version 0.16.0.
Changed in version 0.18.0: The function accepts multiple attributes
-
intersection(other)¶ Group of elements which are in both this Group and another
This method removes duplicate elements and sorts the result. It is synomymous to the & operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the common elements of self and other, without duplicate elements Return type: Group Example
Intersections can be used when the select atoms string would become too complicated. For example to find the water atoms which are within 4.0A of two segments:
>>> shell1 = u.select_atoms('resname SOL and around 4.0 segid 1') >>> shell2 = u.select_atoms('resname SOL and around 4.0 segid 2') >>> common = shell1 & shell2 # or shell1.intersection(shell2)
See also
New in version 0.16.
-
is_strict_subset(other)¶ If this Group is a subset of another Group but not identical
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a strict subset of the other oneReturn type: bool New in version 0.16.
-
is_strict_superset(other)¶ If this Group is a superset of another Group but not identical
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a strict superset of the other oneReturn type: bool New in version 0.16.
-
isdisjoint(other)¶ If the Group has no elements in common with the other Group
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif the two Groups do not have common elementsReturn type: bool New in version 0.16.
-
issubset(other)¶ If all elements of this Group are part of another Group
Note that an empty group is a subset of any group of the same level.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a subset of the other oneReturn type: bool New in version 0.16.
-
issuperset(other)¶ If all elements of another Group are part of this Group
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Trueif this Group is a subset of the other oneReturn type: bool New in version 0.16.
-
isunique¶ Boolean indicating whether all components of the group are unique, i.e., the group contains no duplicates.
Examples
>>> ag = u.atoms[[2, 1, 2, 2, 1, 0]] >>> ag <AtomGroup with 6 atoms> >>> ag.isunique False >>> ag2 = ag.unique >>> ag2 <AtomGroup with 3 atoms> >>> ag2.isunique True
New in version 0.19.0.
-
ix¶ Unique indices of the components in the Group.
- If this Group is an
AtomGroup, these are the indices of theAtominstances. - If it is a
ResidueGroup, these are the indices of theResidueinstances. - If it is a
SegmentGroup, these are the indices of theSegmentinstances.
- If this Group is an
-
ix_array¶ Unique indices of the components in the Group.
For a Group,
ix_arrayis the same asix. This method gives a consistent API between components and groups.See also
-
n_atoms¶ Number of atoms present in the
SegmentGroup, including duplicate segments (and thus, duplicate atoms).Equivalent to
len(self.atoms).
-
n_residues¶ Number of residues present in this
SegmentGroup, including duplicate segments (and thus, residues).Equivalent to
len(self.residues).
-
n_segments¶ Number of segments in the
SegmentGroup.Equivalent to
len(self).
-
pack_into_box(box=None, inplace=True)¶ Shift all
Atomsin this group to the primary unit cell.Parameters: - box (array_like) – Box dimensions, can be either orthogonal or triclinic information.
Cell dimensions must be in an identical to format to those returned
by
MDAnalysis.coordinates.base.Timestep.dimensions,[lx, ly, lz, alpha, beta, gamma]. IfNone, uses these timestep dimensions. - inplace (bool) –
Trueto change coordinates in place.
Returns: coords – Shifted atom coordinates.
Return type: Notes
All atoms will be moved so that they lie between 0 and boxlength \(L_i\) in all dimensions, i.e. the lower left corner of the simulation box is taken to be at (0,0,0):
\[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\]The default is to take unit cell information from the underlying
Timestepinstance. The optional argument box can be used to provide alternative unit cell information (in the MDAnalysis standard format[Lx, Ly, Lz, alpha, beta, gamma]).Works with either orthogonal or triclinic box types.
Note
pack_into_box()is identical towrap()with all default keywords.Note
AtomGroup.pack_into_box()is currently faster thanResidueGroup.pack_into_box()orSegmentGroup.pack_into_box().New in version 0.8.
- box (array_like) – Box dimensions, can be either orthogonal or triclinic information.
Cell dimensions must be in an identical to format to those returned
by
-
residues¶ A
ResidueGroupofResiduespresent in thisSegmentGroup.The
Residuesare ordered locally bySegmentin theSegmentGroup. Duplicates are not removed.
-
rotate(R, point=(0, 0, 0))¶ Apply a rotation matrix R to the selection’s coordinates. \(\mathsf{R}\) is a 3x3 orthogonal matrix that transforms a vector \(\mathbf{x} \rightarrow \mathbf{x}'\):
\[\mathbf{x}' = \mathsf{R}\mathbf{x}\]Atomcoordinates are rotated in-place.Parameters: - R (array_like) – 3x3 rotation matrix
- point (array_like, optional) – Center of rotation
Returns: Return type: self
Notes
By default, rotates about the origin
point=(0, 0, 0). To rotate a groupgaround its center of geometry, useg.rotate(R, point=g.center_of_geometry()).See also
rotateby()- rotate around given axis and angle
MDAnalysis.lib.transformations()- module of all coordinate transforms
-
rotateby(angle, axis, point=None)¶ Apply a rotation to the selection’s coordinates.
Parameters: - angle (float) – Rotation angle in degrees.
- axis (array_like) – Rotation axis vector.
- point (array_like, optional) – Center of rotation. If
Nonethen the center of geometry of this group is used.
Returns: Return type: self
Notes
The transformation from current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\) is
\[\mathbf{x}' = \mathsf{R}\,(\mathbf{x}-\mathbf{p}) + \mathbf{p}\]where \(\mathsf{R}\) is the rotation by angle around the axis going through point \(\mathbf{p}\).
See also
MDAnalysis.lib.transformations.rotation_matrix()calculate()- math:mathsf{R}
-
segments¶ The
SegmentGroupitself.See also
copy- return a true copy of the
SegmentGroup
Changed in version 0.19.0: In previous versions, this returned a copy, but now the
SegmentGroupitself is returned. This should not affect any code but only speed up calculations.
-
subtract(other)¶ Group with elements from this Group that don’t appear in other
The original order of this group is kept, as well as any duplicate elements. If an element of this Group is duplicated and appears in the other Group or Component, then all the occurences of that element are removed from the returned Group.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the elements of self that are not in other, conserves order and duplicates. Return type: Group Example
Unlike
difference()this method will not sort or remove duplicates.>>> ag1 = u.atoms[[3, 3, 2, 2, 1, 1]] >>> ag2 = u.atoms[2] >>> ag3 = ag1 - ag2 # or ag1.subtract(ag2) >>> ag1.indices array([3, 3, 1, 1])
See also
New in version 0.16.
-
symmetric_difference(other)¶ Group of elements which are only in one of this Group or another
This method removes duplicate elements and the result is sorted. It is synomym to the ^ operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the elements that are in self or in other but not in both, without duplicate elements Return type: Group Example
>>> ag1 = u.atoms[[0, 1, 5, 3, 3, 2]] >>> ag2 = u.atoms[[4, 4, 6, 2, 3, 5]] >>> ag3 = ag1 ^ ag2 # or ag1.symmetric_difference(ag2) >>> ag3.indices # 0 and 1 are only in ag1, 4 and 6 are only in ag2 [0, 1, 4, 6]
See also
New in version 0.16.
-
transform(M)¶ Apply homogenous transformation matrix M to the coordinates.
Atomcoordinates are rotated and translated in-place.Parameters: M (array_like) – 4x4 matrix with the rotation in R = M[:3, :3]and the translation int = M[:3, 3].Returns: Return type: self See also
MDAnalysis.lib.transformations()- module of all coordinate transforms
Notes
The rotation \(\mathsf{R}\) is about the origin and is applied before the translation \(\mathbf{t}\):
\[\mathbf{x}' = \mathsf{R}\mathbf{x} + \mathbf{t}\]
-
translate(t)¶ Apply translation vector t to the selection’s coordinates.
Atomcoordinates are translated in-place.Parameters: t (array_like) – vector to translate coordinates with Returns: Return type: self See also
MDAnalysis.lib.transformations()- module of all coordinate transforms
Notes
The method applies a translation to the
AtomGroupfrom current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\):\[\mathbf{x}' = \mathbf{x} + \mathbf{t}\]
-
union(other)¶ Group of elements either in this Group or another
On the contrary to concatenation, this method sort the elements and removes duplicate ones. It is synomymous to the | operator.
Parameters: other (Group or Component) – Group or Component with other.level same as self.level Returns: Group with the combined elements of self and other, without duplicate elements Return type: Group Example
In contrast to
concatenate(), any duplicates are dropped and the result is sorted.>>> ag1 = u.select_atoms('name O') >>> ag2 = u.select_atoms('name N') >>> ag3 = ag1 | ag2 # or ag1.union(ag2) >>> ag3[:3].names array(['N', 'O', 'N'], dtype=object)
See also
New in version 0.16.
-
unique¶ Return a
SegmentGroupcontaining sorted and uniqueSegmentsonly.If the
SegmentGroupis unique, this is the group itself.Examples
>>> sg = u.segments[[2, 1, 2, 2, 1, 0]] >>> sg <SegmentGroup with 6 segments> >>> sg.ix array([2, 1, 2, 2, 1, 0]) >>> sg2 = sg.unique >>> sg2 <SegmentGroup with 3 segments> >>> sg2.ix array([0, 1, 2]) >>> sg2.unique is sg2 True
New in version 0.16.0.
Changed in version 0.19.0: If the
SegmentGroupis already unique,SegmentGroup.uniquenow returns the group itself instead of a copy.
-
unwrap(compound='fragments', reference='com', inplace=True)¶ Move atoms of this group so that bonds within the group’s compounds aren’t split across periodic boundaries.
This function is most useful when atoms have been packed into the primary unit cell, causing breaks mid-molecule, with the molecule then appearing on either side of the unit cell. This is problematic for operations such as calculating the center of mass of the molecule.
+-----------+ +-----------+ | | | | | 6 3 | | 3 | 6 | ! ! | | ! | ! |-5-8 1-2-| ==> | 1-2-|-5-8 | ! ! | | ! | ! | 7 4 | | 4 | 7 | | | | +-----------+ +-----------+
Parameters: - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to unwrap. Note that, in any case, all atoms within each compound must be interconnected by bonds, i.e., compounds must correspond to (parts of) molecules.
- reference ({'com', 'cog', None}, optional) – If
'com'(center of mass) or'cog'(center of geometry), the unwrapped compounds will be shifted so that their individual reference point lies within the primary unit cell. IfNone, no such shift is performed. - inplace (bool, optional) – If
True, coordinates are modified in place.
Returns: coords – Unwrapped atom coordinate array of shape
(n, 3).Return type: Raises: NoDataError– If compound is'molecules'but the underlying topology does not contain molecule information, or if reference is'com'but the topology does not contain masses.ValueError– If reference is not one of'com','cog', orNone, or if reference is'com'and the total mass of any compound is zero.
Note
Be aware of the fact that only atoms belonging to the group will be unwrapped! If you want entire molecules to be unwrapped, make sure that all atoms of these molecules are part of the group.
An AtomGroup containing all atoms of all fragments in the group
agcan be created with:all_frag_atoms = sum(ag.fragments)
See also
make_whole(),wrap(),pack_into_box(),apply_PBC()New in version 0.20.0.
-
wrap(compound='atoms', center='com', box=None, inplace=True)¶ Shift the contents of this group back into the primary unit cell according to periodic boundary conditions.
Specifying a compound will keep the
Atomsin each compound together during the process. If compound is different from'atoms', each compound as a whole will be shifted so that its center lies within the primary unit cell.Parameters: - compound ({'atoms', 'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during wrapping. Note that,
in any case, only the positions of
Atomsbelonging to the group will be taken into account. - center ({'com', 'cog'}) – How to define the center of a given group of atoms. If compound is
'atoms', this parameter is meaningless and therefore ignored. - box (array_like, optional) –
The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by
MDAnalysis.coordinates.base.Timestep.dimensions:[lx, ly, lz, alpha, beta, gamma].If
None, uses the dimensions of the current time step. - inplace (bool, optional) – If
True, coordinates will be changed in place.
Returns: Array of wrapped atom coordinates of dtype np.float32 and shape
(len(self.atoms.n_atoms), 3)Return type: Raises: ValueError– If compound is not one of'atoms','group','segments','residues','molecules', or'fragments'.NoDataError– If compound is'molecule'but the topology doesn’t contain molecule information (molnums) or if compound is'fragments'but the topology doesn’t contain bonds or if center is'com'but the topology doesn’t contain masses.
Notes
All atoms of the group will be moved so that the centers of its compounds lie within the primary periodic image. For orthorhombic unit cells, the primary periodic image is defined as the half-open interval \([0,L_i)\) between \(0\) and boxlength \(L_i\) in all dimensions \(i\in\{x,y,z\}\), i.e., the origin of the of the simulation box is taken to be at the origin \((0,0,0)\) of the euclidian coordinate system. A compound center residing at position \(x_i\) in dimension \(i\) will be shifted to \(x_i'\) according to
\[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\,.\]When specifying a compound, the translation is calculated based on each compound. The same translation is applied to all atoms within this compound, meaning it will not be broken by the shift. This might however mean that not all atoms of a compound will be inside the unit cell after wrapping, but rather will be the center of the compound.
Be aware of the fact that only atoms belonging to the group will be taken into account!
center allows to define how the center of each group is computed. This can be either
'com'for center of mass, or'cog'for center of geometry.box allows a unit cell to be given for the transformation. If not specified, the
dimensionsinformation from the currentTimestepwill be used.Note
AtomGroup.wrap()is currently faster thanResidueGroup.wrap()orSegmentGroup.wrap().See also
pack_into_box(),unwrap(),MDanalysis.lib.distances.apply_PBC()New in version 0.9.2.
Changed in version 0.20.0: The method only acts on atoms belonging to the group and returns the wrapped positions as a
numpy.ndarray. Added optional argument inplace.- compound ({'atoms', 'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during wrapping. Note that,
in any case, only the positions of
-
-
class
MDAnalysis.core.groups.UpdatingAtomGroup(base_group, selections, strings)[source]¶ AtomGroupsubclass that dynamically updates its selected atoms.Accessing any attribute/method of an
UpdatingAtomGroupinstance triggers a check for the last frame the group was updated. If the last frame matches the current trajectory frame, the attribute is returned normally; otherwise the group is updated (the stored selections are re-applied), and only then is the attribute returned.New in version 0.16.0.
Parameters: - base_group (
AtomGroup) – group on which selections are to be applied. - selections (a tuple of
Selection) – instances selections ready to be applied to base_group.
-
atoms¶ Get a static
AtomGroupidentical to the group of currently selectedAtomsin theUpdatingAtomGroup.By returning a static
AtomGroupit becomes possible to compare the contents of the group between trajectory frames. See the Example below.Note
The
atomsattribute of anUpdatingAtomGroupbehaves differently fromAtomGroup.atoms: the latter returns theAtomGroupitself whereas the former returns aAtomGroupand not anUpdatingAtomGroup(for this, useUpdatingAtomGroup.copy()).Example
The static
atomsallows comparison of groups of atoms between frames. For example, track water molecules that move in and out of a solvation shell of a protein:u = mda.Universe(TPR, XTC) water_shell = u.select_atoms("name OW and around 3.5 protein", updating=True) water_shell_prev = water_shell.atoms for ts in u.trajectory: exchanged = water_shell - water_shell_prev print(ts.time, "waters in shell =", water_shell.n_residues) print(ts.time, "waters that exchanged = ", exchanged.n_residues) print(ts.time, "waters that remained bound = ", water_shell.n_residues - exchanged.n_residues) water_shell_prev = water_shell.atoms
By remembering the atoms of the current time step in water_shell_prev, it becomes possible to use the
subtraction of AtomGroupsto find the water molecules that changed.See also
copy- return a true copy of the
UpdatingAtomGroup
-
copy()[source]¶ Get another
UpdatingAtomGroupidentical to this one.New in version 0.19.0.
-
is_uptodate¶ Checks whether the selection needs updating based on frame number only.
Modifications to the coordinate data that render selections stale are not caught, and in those cases
is_uptodatemay return an erroneous value.Returns: Trueif the group’s selection is up-to-date,Falseotherwise.Return type: bool
- base_group (
11.1.2.1.2. Chemical units¶
-
class
MDAnalysis.core.groups.Atom(ix, u)[source]¶ Atombase class.This class is used by a
Universefor generating its Topology-specificAtomclass. All theTopologyAttrcomponents are obtained fromComponentBase, so this class only includes ad-hoc methods specific toAtoms.-
force¶ Force on the atom.
The force can be changed by assigning an array of shape
(3,).Note
changing the force is not reflected in any files; reading any frame from the trajectory will replace the change with that from the file
Raises: NoDataError– If the underlyingTimestepdoes not containforces.
-
ix¶ Unique index of this component.
If this component is an
Atom, this is the index of theAtom. If it is aResidue, this is the index of theResidue. If it is aSegment, this is the index of theSegment.
-
ix_array¶ Unique index of this component as an array.
This method gives a consistent API between components and groups.
See also
-
position¶ Coordinates of the atom.
The position can be changed by assigning an array of length (3,).
Note
changing the position is not reflected in any files; reading any frame from the trajectory will replace the change with that from the file
Raises: NoDataError– If the underlyingTimestepdoes not containpositions.
-
velocity¶ Velocity of the atom.
The velocity can be changed by assigning an array of shape
(3,).Note
changing the velocity is not reflected in any files; reading any frame from the trajectory will replace the change with that from the file
Raises: NoDataError– If the underlyingTimestepdoes not containvelocities.
-
-
class
MDAnalysis.core.groups.Residue(ix, u)[source]¶ Residuebase class.This class is used by a
Universefor generating its Topology-specificResidueclass. All theTopologyAttrcomponents are obtained fromComponentBase, so this class only includes ad-hoc methods specific toResidues.-
ix¶ Unique index of this component.
If this component is an
Atom, this is the index of theAtom. If it is aResidue, this is the index of theResidue. If it is aSegment, this is the index of theSegment.
-
ix_array¶ Unique index of this component as an array.
This method gives a consistent API between components and groups.
See also
-
-
class
MDAnalysis.core.groups.Segment(ix, u)[source]¶ Segmentbase class.This class is used by a
Universefor generating its Topology-specificSegmentclass. All theTopologyAttrcomponents are obtained fromComponentBase, so this class only includes ad-hoc methods specific toSegments.Deprecated since version 0.16.2: Instant selectors of
Segmentswill be removed in the 1.0 release.Changed in version 1.0.0: Removed instant selectors, use either segment.residues[…] to select residue by number, or segment.residues[segment.residue.resnames = …] to select by resname.
-
ix¶ Unique index of this component.
If this component is an
Atom, this is the index of theAtom. If it is aResidue, this is the index of theResidue. If it is aSegment, this is the index of theSegment.
-
ix_array¶ Unique index of this component as an array.
This method gives a consistent API between components and groups.
See also
-
residues¶ A
ResidueGroupofResiduespresent in thisSegment.
-
11.1.2.1.3. Levels¶
Each of the above classes has a level attribute. This can be used to verify that two objects are of the same level, or to access a particular class:
u = mda.Universe()
ag = u.atoms[:10]
at = u.atoms[11]
ag.level == at.level # Returns True
ag.level.singular # Returns Atom class
at.level.plural # Returns AtomGroup class