Atom Group

This module defines AtomGroup class that stores atomic data and multiple coordinate sets in 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 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.

getAcceptors()

Returns acceptors. Use setAcceptors() for setting acceptors.

getAltlocs()

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

getAngles()

Returns angles. Use setAngles() for setting angles.

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'.

getBonds()

Returns bonds. Use setBonds() or inferBonds() for setting bonds.

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.

getCrossterms()

Returns crossterms. Use setCrossterms() for setting crossterms.

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.

getDihedrals()

Returns dihedrals. Use setDihedrals() for setting dihedrals.

getDonors()

Returns donors. Use setDonors() for setting donors.

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() or AtomGroup.inferBonds(). 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 _'.

getImpropers()

Returns impropers. Use setImpropers() for setting impropers.

getMasses()

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

getNBExclusions()

Returns nbexclusions. Use setNBExclusions() for setting nbexclusions.

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.

getSecclasses()

Return a copy of secondary structure classs. Secondary structure classs can be used in atom selections, e.g. 'secclass 2', 'secclass -1'.

getSecids()

Return a copy of secondary structure identifiers. Secondary structure identifiers can be used in atom selections, e.g. 'secid A B', 'secid 1 2'.

getSecindices()

Return a copy of secondary structure indexs. Secondary structure indexs can be used in atom selections, e.g. 's', 'e', 'c', 'i', 'n', 'd', 'e', 'x', ' ', '2'.

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.

getSequence(**kwargs)

Returns one-letter sequence string for amino acids. When allres keyword argument is True, sequence will include all residues (e.g. water molecules) in the chain and X will be used for non-standard residue names.

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'.

inferBonds(max_bond=1.6, min_bond=0, set_bonds=True)

Returns bonds based on distances max_bond and min_bond.

isDataLabel(label)

Returns True if data associated with label is present.

isFlagLabel(label)

Returns True if flags associated with label are present.

iterAcceptors()

Yield acceptors. Use setAcceptors() for setting acceptors.

iterAngles()

Yield angles. Use setAngles() for setting angles.

iterAtoms()

Yield atom instances.

iterBonds()

Yield bonds. Use setBonds() or inferBonds for setting bonds.

iterChains()

Iterate over chains.

iterCoordsets()

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

iterCrossterms()

Yield crossterms. Use setCrossterms() for setting crossterms.

iterDihedrals()

Yield dihedrals. Use setDihedrals() for setting dihedrals.

iterDonors()

Yield donors. Use setDonors() for setting donors.

iterFragments()

Yield connected atom subsets as Selection instances.

iterImpropers()

Yield impropers. Use setImpropers() for setting impropers.

iterNBExclusions()

Yield nbexclusions. Use setNBExclusions() for setting nbexclusions.

iterResidues()

Iterate over residues.

iterSegments()

Iterate over segments.

numAcceptors()

Returns number of acceptors. Use setAcceptors() for setting acceptors.

numAngles()

Returns number of angles. Use setAngles() for setting angles.

numAtoms(flag=None)

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

numBonds()

Returns number of bonds. Use setBonds() or inferBonds() 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.

numCrossterms()

Returns number of crossterms. Use setCrossterms() for setting crossterms.

numDihedrals()

Returns number of dihedrals. Use setDihedrals() for setting dihedrals.

numDonors()

Returns number of donors. Use setDonors() for setting donors.

numFragments()

Returns number of connected atom subsets.

numImpropers()

Returns number of impropers. Use setImpropers() for setting impropers.

numNBExclusions()

Returns number of nbexclusions. Use setNBExclusions() for setting nbexclusions.

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.

setAcceptors(acceptors)

Set covalent acceptors between atoms. acceptors must be a list or an array of pairs of indices. All acceptors must be set at once. Acceptoring information can be used to make atom selections, e.g. "acceptored to index 1". See select module documentation for details. Also, a data array with number of acceptors will be generated and stored with label numacceptors. This can be used in atom selections, e.g. 'numacceptors 0' can be used to select ions in a system. If acceptors is empty or None, then all acceptors will be removed for this AtomGroup.

setAltlocs(data)

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

setAngles(angles)

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

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. If bonds is empty or None, then all bonds will be removed for this AtomGroup.

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.

setCrossterms(crossterms)

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

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.

setDihedrals(dihedrals)

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

setDonors(donors)

Set covalent donors between atoms. donors must be a list or an array of pairs of indices. All donors must be set at once. Donoring information can be used to make atom selections, e.g. "donored to index 1". See select module documentation for details. Also, a data array with number of donors will be generated and stored with label numdonors. This can be used in atom selections, e.g. 'numdonors 0' can be used to select ions in a system. If donors is empty or None, then all donors will be removed for this AtomGroup.

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 _'.

setImpropers(impropers)

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

setMasses(data)

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

setNBExclusions(nbexclusions)

Set nbexclusions between atoms. nbexclusions must be a list or an array of pairs of indices. All nbexclusions must be set at once. Acceptoring information can be used to make atom selections, e.g. "nbexclusioned to index 1". See select module documentation for details. Also, a data array with number of nbexclusions will be generated and stored with label numnbexclusions. This can be used in atom selections, e.g. 'numnbexclusions 0' can be used to select ions in a system. If nbexclusions is empty or None, then all nbexclusions will be removed for this AtomGroup.

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.

setSecclasses(data)

Set secondary structure classs. Secondary structure classs can be used in atom selections, e.g. 'secclass 2', 'secclass -1'.

setSecids(data)

Set secondary structure identifiers. Secondary structure identifiers can be used in atom selections, e.g. 'secid A B', 'secid 1 2'.

setSecindices(data)

Set secondary structure indexs. Secondary structure indexs can be used in atom selections, e.g. 's', 'e', 'c', 'i', 'n', 'd', 'e', 'x', ' ', '2'.

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'.

toAtomGroup()

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

toTEMPyAtoms()

Returns a BioPy.PDB Atom or Structure object as appropriate

toTEMPyStructure()

Returns a BioPy.PDB Atom or Structure object as appropriate