Atom Map

This module defines AtomMap class that allows for pointing atoms in arbitrary order.

How AtomMap works

AtomMap class adds great flexibility to manipulating atomic data.

First let’s see how an instance of Selection (Chain, or Residue) works. Below table shows indices for a selection of atoms in an AtomGroup and values returned when getNames(), getResnames() and getResnums() methods are called.

Atom Subset

Indices	Names	Resnames	Resnums
0	N	PHE	1
1	CA	PHE	1
2	C	PHE	1
3	O	PHE	1
4	CB	PHE	1
5	CG	PHE	1
6	CD1	PHE	1
7	CD2	PHE	1
8	CE1	PHE	1
9	CE2	PHE	1
10	CZ	PHE	1

Selection instances keep indices ordered and do not allow duplicate values, hence their use is limited. In an AtomMap, indices do not need to be sorted, duplicate indices may exist, even “DUMMY” atoms are allowed.

Let’s say we instantiate the following AtomMap:

amap = AtomMap(atomgroup, indices=[0, 1, 3, 8, 8, 9, 10],
               mapping=[5, 6, 7, 0, 1, 2, 3])

The size of the AtomMap based on this mapping is 8, since the larger mapping is 7.

Calling the same functions for this AtomMap instance would result in the following:

Atom Map

Mapping	Indices	Names	Resnames	Resnums	MappedFlags	DummyFlags
0	8	CE1	PHE	1	1	0
1	8	CE1	PHE	1	1	0
2	9	CE2	PHE	1	1	0
3	10	CZ	PHE	1	1	0
4				0	0	1
5	0	N	PHE	1	1	0
6	1	CA	PHE	1	1	0
7	3	O	PHE	1	1	0

For unmapped atoms, numeric attributes are set to 0, others to empty string, i.e. "".

See also

AtomMap are used by proteins module functions that match or map protein chains. Heterogeneous X-ray Structures and Multimeric Structures examples that make use of these functions and AtomMap class.

class AtomMap(ag, indices, acsi=None, **kwargs)

A class for mapping atomic data.

Instantiate an atom map.

Parameters:

• ag – AtomGroup instance from which atoms are mapped
• indices – indices of mapped atoms
• acsi – active coordinate set index, defaults is that of ag
• mapping – mapping of atom indices
• dummies – dummy atom indices
• title – title of the instance, default is ‘Unknown’

mapping and dummies arrays must be provided together. Length of mapping must be equal to length of indices. Elements of mapping must be an ordered in ascending order. When dummy atoms are present, number of atoms is the sum of lengths of mapping and dummies.

Following built-in functions are customized for this class:

• len() returns the number of atoms in the instance.
• iter() yields Atom instances.
• Indexing returns an Atom or an AtomMap instance depending on the type and value of the index.

copy()

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

getACSIndex()

Returns index of the coordinate set.

getACSLabel()

Returns active coordinate set label.

getAltlocs()

Return a copy of alternate location indicators. Entries for dummy atoms will be ''.

getAnisous()

Return a copy of anisotropic temperature factors. Entries for dummy atoms will be 0.0.

getAnistds()

Return a copy of standard deviations for anisotropic temperature factors. Entries for dummy atoms will be 0.0.

getAtomGroup()

Returns associated atom group.

getBetas()

Return a copy of β-values (or temperature factors). Entries for dummy atoms will be 0.0.

getCSLabels()

Returns coordinate set labels.

getCharges()

Return a copy of partial charges. Entries for dummy atoms will be 0.0.

getChids()

Return a copy of chain identifiers. Entries for dummy atoms will be ''.

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. Entries for dummy atoms will be 0.

getCoords()

Returns a copy of coordinates from the active coordinate set.

getCoordsets(indices=None)

Returns coordinate set(s) at given indices, which may be an integer or a list/array of integers.

getData(label)

Returns a copy of data associated with label, if it is 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. Entries for dummy atoms will be ''.

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. Entries for dummy atoms will be 0.

getHierView(**kwargs)

Returns a hierarchical view of the this chain.

getIcodes()

Return a copy of insertion codes. Entries for dummy atoms will be ''.

getIndices()

Returns a copy of indices of atoms, with maximum integer value dummies.

getMapping()

Returns a copy of mapping of indices.

getMasses()

Return a copy of masses. Entries for dummy atoms will be 0.0.

getNames()

Return a copy of names. Entries for dummy atoms will be ''.

getOccupancies()

Return a copy of occupancy values. Entries for dummy atoms will be 0.0.

getRadii()

Return a copy of radii. Entries for dummy atoms will be 0.0.

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. Entries for dummy atoms will be 0.

getResnames()

Return a copy of residue names. Entries for dummy atoms will be ''.

getResnums()

Return a copy of residue numbers. Entries for dummy atoms will be 0.

getSecclasses()

Return a copy of secondary structure classs. Entries for dummy atoms will be 0.

getSecids()

Return a copy of secondary structure identifiers. Entries for dummy atoms will be ''.

getSecindices()

Return a copy of secondary structure indexs. Entries for dummy atoms will be 0.

getSecstrs()

Return a copy of secondary structure assignments. Entries for dummy atoms will be ''.

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. Entries for dummy atoms will be 0.

getSegnames()

Return a copy of segment names. Entries for dummy atoms will be ''.

getSelstr()

Returns selection string that selects mapped atoms.

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). Entries for dummy atoms will be 0.

getTitle()

Returns title of the instance.

getTypes()

Return a copy of types. Entries for dummy atoms will be ''.

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 formed by the atom. Use setAcceptors() for setting acceptors.

iterAngles()

Yield angles formed by the atom. Use setAngles() for setting angles.

iterAtoms()

Yield atoms, and None for dummies.

iterBonds()

Yield bonds formed by the atom. Use setBonds() or inferBonds() for setting bonds.

iterCoordsets()

Yield copies of coordinate sets.

iterCrossterms()

Yield crossterms formed by the atom. Use setCrossterms() for setting crossterms.

iterDihedrals()

Yield dihedrals formed by the atom. Use setDihedrals() for setting dihedrals.

iterDonors()

Yield donors formed by the atom. Use setDonors() for setting donors.

iterImpropers()

Yield impropers formed by the atom. Use setImpropers() for setting impropers.

iterNBExclusions()

Yield nbexclusions formed by the atom. Use setNBExclusions() for setting nbexclusions.

numAtoms(flag=None)

Returns number of atoms.

numCoordsets()

Returns number of coordinate sets.

numDummies()

Returns number of dummy atoms.

numMapped()

Returns number of mapped atoms.

select(selstr, **kwargs)

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

setACSIndex(index)

Set coordinates at index active.

setCoords(coords)

Set coordinates of atoms in the active coordinate set.

setTitle(title)

Set title of the instance.

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