Atom Map

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

How AtomMap’s work

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)[source]

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()[source]

Returns a copy of coordinates from the active coordinate set.

getCoordsets(indices=None)[source]

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

getData(label)[source]

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)[source]

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

getIcodes()

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

getIndices()[source]

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

getMapping()[source]

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.

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()[source]

Returns selection string that selects mapped atoms.

getSerials()

Return a copy of serial numbers (from file). Entries for dummy atoms will be 0.

getTitle()[source]

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.

iterAtoms()[source]

Yield atoms, and None for dummies.

iterCoordsets()[source]

Yield copies of coordinate sets.

numAtoms(flag=None)[source]

Returns number of atoms.

numCoordsets()

Returns number of coordinate sets.

numDummies()[source]

Returns number of dummy atoms.

numMapped()[source]

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)[source]

Set coordinates of atoms in the active coordinate set.

setTitle(title)[source]

Set title of the instance.