Atom Group

This module defines AtomGroup class that stores atomic data and multiple coordinate sets in numpy.ndarray instances.

class AtomGroup(title='Unnamed')

A class for storing and accessing atomic data. The number of atoms of the atom group is inferred at the first set method call from the size of the data array.

Atomic data

All atomic data is stored in numpy.ndarray instances.

Get and set methods

get methods, e.g. getResnames(), return copies of the data arrays.

set methods, e.g. setResnums(), accept data in list() or ndarray instances. The length of the list or array must match the number of atoms in the atom group. These methods set attributes of all atoms at once.

Coordinate sets

Atom groups with multiple coordinate sets may have one of these sets as the active coordinate set. The active coordinate set may be changed using setACSIndex() method. getCoords() returns coordinates from the active set.

Atom subsets

To access and modify data associated with a subset of atoms in an atom group, Selection instances may be used. A Selection has initially the same coordinate set as the active coordinate set, but it may be changed using Selection.setACSIndex() method.

Customizations

Following built-in functions are customized for this class:

• len() returns the number of atoms, i.e. numAtoms()
• iter() yields Atom instances

Indexing AtomGroup instances by:

• int (int()), e.g, 10, returns an Atom
• slice (slice()), e.g, 10:20:2, returns a Selection
• segment name (str()), e.g. 'PROT', returns a a Segment
• chain identifier (str()), e.g. 'A', returns a a Chain
• [segment name,] chain identifier, residue number[, insertion code] (tuple()), e.g. 'A', 10 or 'A', 10, 'B' or 'PROT', 'A', 10, 'B', returns a Residue

Addition

Addition of two AtomGroup instances, let’s say A and B, results in a new AtomGroup instance, say C. C stores an independent copy of the data of A and B. If A or B is missing a certain data type, zero values will be used for that part in C. If A and B has same number of coordinate sets, C will have a copy of all coordinate sets, otherwise C will have a single coordinate set, which is a copy of of active coordinate sets of A and B.

addCoordset(coords, label=None)

Add a coordinate set. coords argument may be an object with getCoordsets() method.

copy()

Returns a copy of atoms (and atomic data) in an AtomGroup instance.

delCoordset(index)

Delete a coordinate set from the atom group.

delData(label)

Returns data associated with label and remove from the instance. If data associated with label is not found, return None.

delFlags(label)

Returns flags associated with label and remove from the instance. If flags associated with label is not found, return None.

getACSIndex()

Returns index of the coordinate set.

getACSLabel()

Returns active coordinate set label.

getAltlocs()

Return a copy of alternate location indicators. Alternate location indicators can be used in atom selections, e.g. 'altloc A B', 'altloc _'.

getAnisous()

Return a copy of anisotropic temperature factors.

getAnistds()

Return a copy of standard deviations for anisotropic temperature factors.

getBetas()

Return a copy of β-values (or temperature factors). β-values can be used in atom selections, e.g. 'beta 555.55', 'beta 0 to 500', 'beta 0:500', 'beta < 500'.

getBySerial(serial, stop=None, step=None)

Get an atom(s) by serial number (range). serial must be zero or a positive integer. stop may be None, or an integer greater than serial. getBySerial(i, j) will return atoms whose serial numbers are i+1, i+2, ..., j-1. Atom whose serial number is stop will be excluded as it would be in indexing a Python list. step (default is 1) specifies increment. If atoms with matching serial numbers are not found, None will be returned.

getCSLabels()

Returns coordinate set labels.

getCharges()

Return a copy of partial charges. Partial charges can be used in atom selections, e.g. 'charge 1', 'abs(charge) == 1', 'charge < 0'.

getChids()

Return a copy of chain identifiers. Chain identifiers can be used in atom selections, e.g. 'chain A', 'chid A B C', 'chain _'. Note that chid is a synonym for chain.

getChindices()

Return a copy of chain indices. Chain indices are assigned to subsets of atoms with distinct pairs of chain identifier and segment name. Chain indices start from zero, are incremented by one, and are assigned in the order of appearance in AtomGroup instance. Chain indices can be used in atom selections, e.g. 'chindex 0'.

getCoords()

Returns a copy of coordinates from active coordinate set.

getCoordsets(indices=None)

Returns a copy of coordinate set(s) at given indices. indices may be an integer, a list of integers, or None meaning all coordinate sets.

getData(label)

Returns a copy of the data array associated with label, or None if such data is not present.

getDataLabels(which=None)

Returns data labels. For which='user', return only labels of user provided data.

getDataType(label)

Returns type of the data (i.e. data.dtype) associated with label, or None label is not used.

getElements()

Return a copy of element symbols. Element symbols can be used in atom selections, e.g. 'element C O N'.

getFlagLabels(which=None)

Returns flag labels. For which='user', return labels of user or parser (e.g. hetatm) provided flags, for which='all' return all possible Atom Flags labels in addition to those present in the instance.

getFlags(label)

Returns a copy of atom flags for given label, or None when flags for label is not set.

getFragindices()

Return a copy of fragment indices. Fragment indices are assigned to connected subsets of atoms. Bonds needs to be set using AtomGroup.setBonds() method. Fragment indices start from zero, are incremented by one, and are assigned in the order of appearance in AtomGroup instance. Fragment indices can be used in atom selections, e.g. 'fragindex 0', 'fragment 1'. Note that fragment is a synonym for fragindex.

getHierView(**kwargs)

Returns a hierarchical view of the atom group.

getIcodes()

Return a copy of insertion codes. Insertion codes can be used in atom selections, e.g. 'icode A', 'icode _'.

getMasses()

Return a copy of masses. Masses can be used in atom selections, e.g. '12 <= mass <= 13.5'.

getNames()

Return a copy of names. Names can be used in atom selections, e.g. 'name CA CB'.

getOccupancies()

Return a copy of occupancy values. Occupancy values can be used in atom selections, e.g. 'occupancy 1', 'occupancy > 0'.

getRadii()

Return a copy of radii. Radii can be used in atom selections, e.g. 'radii < 1.5', 'radii ** 2 < 2.3'.

getResindices()

Return a copy of residue indices. Residue indices are assigned to subsets of atoms with distinct sequences of residue number, insertion code, chain identifier, and segment name. Residue indices start from zero, are incremented by one, and are assigned in the order of appearance in AtomGroup instance. Residue indices can be used in atom selections, e.g. 'resindex 0'.

getResnames()

Return a copy of residue names. Residue names can be used in atom selections, e.g. 'resname ALA GLY'.

getResnums()

Return a copy of residue numbers. Residue numbers can be used in atom selections, e.g. 'resnum 1 2 3', 'resnum 120A 120B', 'resnum 10 to 20', 'resnum 10:20:2', 'resnum < 10'. Note that resid is a synonym for resnum.

getSecstrs()

Return a copy of secondary structure assignments. Secondary structure assignments can be used in atom selections, e.g. 'secondary H E', 'secstr H E'. Note that secstr is a synonym for secondary.

getSegindices()

Return a copy of segment indices. Segment indices are assigned to subsets of atoms with distinct segment names. Segment indices start from zero, are incremented by one, and are assigned in the order of appearance in AtomGroup instance. Segment indices can be used in atom selections, e.g. 'segindex 0'.

getSegnames()

Return a copy of segment names. Segment names can be used in atom selections, e.g. 'segment PROT', 'segname PROT'. Note that segname is a synonym for segment.

getSerials()

Return a copy of serial numbers (from file). Serial numbers can be used in atom selections, e.g. 'serial 1 2 3', 'serial 1 to 10', 'serial 1:10:2', 'serial < 10'.

getTitle()

Returns title of the instance.

getTypes()

Return a copy of types. Types can be used in atom selections, e.g. 'type CT1 CT2 CT3'.

isDataLabel(label)

Returns True if data associated with label is present.

isFlagLabel(label)

Returns True if flags associated with label are present.

iterAtoms()

Yield atom instances.

iterBonds()

Yield bonds. Use setBonds() for setting bonds.

iterChains()

Iterate over chains.

iterCoordsets()

Iterate over coordinate sets by returning a copy of each coordinate set.

iterFragments()

Yield connected atom subsets as Selection instances.

iterResidues()

Iterate over residues.

iterSegments()

Iterate over chains.

numAtoms(flag=None)

Returns number of atoms, or number of atoms with given flag.

numBonds()

Returns number of bonds. Use setBonds() for setting bonds.

numBytes(all=False)

Returns number of bytes used by atomic data arrays, such as coordinate, flag, and attribute arrays. If all is True, internal arrays for indexing hierarchical views, bonds, and fragments will also be included. Note that memory usage of Python objects is not taken into account and that this may change in the future.

numChains()

Returns number of chains.

numCoordsets()

Returns number of coordinate sets.

numFragments()

Returns number of connected atom subsets.

numResidues()

Returns number of residues.

numSegments()

Returns number of segments.

select(selstr, **kwargs)

Returns atoms matching selstr criteria. See select module documentation for details and usage examples.

setACSIndex(index)

Set the coordinate set at index active.

setACSLabel(label)

Set active coordinate set label.

setAltlocs(data)

Set alternate location indicators. Alternate location indicators can be used in atom selections, e.g. 'altloc A B', 'altloc _'.

setAnisous(data)

Set anisotropic temperature factors.

setAnistds(data)

Set standard deviations for anisotropic temperature factors.

setBetas(data)

Set β-values (or temperature factors). β-values can be used in atom selections, e.g. 'beta 555.55', 'beta 0 to 500', 'beta 0:500', 'beta < 500'.

setBonds(bonds)

Set covalent bonds between atoms. bonds must be a list or an array of pairs of indices. All bonds must be set at once. Bonding information can be used to make atom selections, e.g. "bonded to index 1". See select module documentation for details. Also, a data array with number of bonds will be generated and stored with label numbonds. This can be used in atom selections, e.g. 'numbonds 0' can be used to select ions in a system.

setCSLabels(labels)

Set coordinate set labels. labels must be a list of strings.

setCharges(data)

Set partial charges. Partial charges can be used in atom selections, e.g. 'charge 1', 'abs(charge) == 1', 'charge < 0'.

setChids(data)

Set chain identifiers. Chain identifiers can be used in atom selections, e.g. 'chain A', 'chid A B C', 'chain _'. Note that chid is a synonym for chain.

setCoords(coords, label='')

Set coordinates of atoms. coords may be any array like object or an object instance with getCoords() method. If the shape of coordinate array is (n_csets > 1, n_atoms, 3), it will replace all coordinate sets and the active coordinate set index will reset to zero. This situation can be avoided using addCoordset(). If shape of coords is (n_atoms, 3) or (1, n_atoms, 3), it will replace the active coordinate set. label argument may be used to label coordinate set(s). label may be a string or a list of strings length equal to the number of coordinate sets.

setData(label, data)

Store atomic data under label, which must:

• start with a letter
• contain only alphanumeric characters and underscore
• not be a reserved word (see listReservedWords())

data must be a list() or a ndarray and its length must be equal to the number of atoms. If the dimension of the data array is 1, i.e. data.ndim==1, label may be used to make atom selections, e.g. "label 1 to 10" or "label C1 C2". Note that, if data with label is present, it will be overwritten.

setElements(data)

Set element symbols. Element symbols can be used in atom selections, e.g. 'element C O N'.

setFlags(label, flags)

Set atom flags for label.

setIcodes(data)

Set insertion codes. Insertion codes can be used in atom selections, e.g. 'icode A', 'icode _'.

setMasses(data)

Set masses. Masses can be used in atom selections, e.g. '12 <= mass <= 13.5'.

setNames(data)

Set names. Names can be used in atom selections, e.g. 'name CA CB'.

setOccupancies(data)

Set occupancy values. Occupancy values can be used in atom selections, e.g. 'occupancy 1', 'occupancy > 0'.

setRadii(data)

Set radii. Radii can be used in atom selections, e.g. 'radii < 1.5', 'radii ** 2 < 2.3'.

setResnames(data)

Set residue names. Residue names can be used in atom selections, e.g. 'resname ALA GLY'.

setResnums(data)

Set residue numbers. Residue numbers can be used in atom selections, e.g. 'resnum 1 2 3', 'resnum 120A 120B', 'resnum 10 to 20', 'resnum 10:20:2', 'resnum < 10'. Note that resid is a synonym for resnum.

setSecstrs(data)

Set secondary structure assignments. Secondary structure assignments can be used in atom selections, e.g. 'secondary H E', 'secstr H E'. Note that secstr is a synonym for secondary.

setSegnames(data)

Set segment names. Segment names can be used in atom selections, e.g. 'segment PROT', 'segname PROT'. Note that segname is a synonym for segment.

setSerials(data)

Set serial numbers (from file). Serial numbers can be used in atom selections, e.g. 'serial 1 2 3', 'serial 1 to 10', 'serial 1:10:2', 'serial < 10'.

setTitle(title)

Set title of the instance.

setTypes(data)

Set types. Types can be used in atom selections, e.g. 'type CT1 CT2 CT3'.