AtomArray

class biotite.structure.AtomArray(length)

Bases: _AtomArrayBase

An array representation of a model consisting of multiple atoms.

An AtomArray can be seen as a list of Atom instances. Instead of using directly a list, this class uses an NumPy ndarray for each annotation category and the coordinates. These coordinates can be accessed directly via the coord attribute. The annotations are accessed either via the category as attribute name or the get_annotation(), set_annotation() method. Usage of custom annotations is achieved via add_annotation() or set_annotation(). A detailed description of each annotation category can be viewed here.

In order to get an an subarray of an AtomArray, NumPy style indexing is used. This includes slices, boolean arrays, index arrays and even Ellipsis notation. Using a single integer as index returns a single Atom instance.

Inserting or appending an AtomArray to another AtomArray is done with the ‘+’ operator. Only the annotation categories, which are existing in both arrays, are transferred to the new array. For a list of AtomArray objects, use concatenate().

Optionally, an AtomArray can store chemical bond information via a BondList object. It can be accessed using the bonds attribute. If no bond information is available, bonds is None. Consequently the bond information can be removed from the AtomArray, by setting bonds to None. When indexing the AtomArray the atom indices in the associated BondList are updated as well, hence the indices in the BondList will always point to the same atoms. If two AtomArray instances are concatenated, the resulting AtomArray will contain the merged BondList if at least one of the operands contains bond information.

The box attribute contains the box vectors of the unit cell or the MD simulation box, respectively. Hence, it is a 3 x 3 ndarray with the vectors in the last dimension. If no box is provided, the attribute is None. Setting the box attribute to None means removing the box from the atom array.

Parameters:

lengthint

The fixed amount of atoms in the array.

Attributes:

{annot}ndarray

Multiple n-length annotation arrays.

coordndarray, dtype=float, shape=(n,3)

ndarray containing the x, y and z coordinate of the atoms.

bondsBondList or None

A BondList, specifying the indices of atoms that form a chemical bond.

boxndarray, dtype=float, shape=(3,3) or None

The surrounding box. May represent a MD simulation box or a crystallographic unit cell.

shapetuple of int

Tuple of array dimensions.

See also

AtomArrayStack

Representation of multiple structure models.

Examples

Creating an atom array from atoms:

>>> atom1 = Atom([1,2,3], chain_id="A")
>>> atom2 = Atom([2,3,4], chain_id="A")
>>> atom3 = Atom([3,4,5], chain_id="B")
>>> atom_array = array([atom1, atom2, atom3])
>>> print(atom_array.array_length())
3

Accessing an annotation array:

>>> print(atom_array.chain_id)
['A' 'A' 'B']

Accessing the coordinates:

>>> print(atom_array.coord)
[[1. 2. 3.]
 [2. 3. 4.]
 [3. 4. 5.]]

NumPy style filtering:

>>> atom_array = atom_array[atom_array.chain_id == "A"]
>>> print(atom_array.array_length())
2

Inserting an atom array:

>>> insert = array([Atom([7,8,9], chain_id="C")])
>>> atom_array = atom_array[0:1] + insert + atom_array[1:2]
>>> print(atom_array.chain_id)
['A' 'C' 'A']

add_annotation(category, dtype)

Add an annotation category, if not already existing.

Initially the new annotation is filled with the zero representation of the given type.

Parameters:

categorystr

The annotation category to be added.

dtypetype or str

A type instance or a valid NumPy dtype string. Defines the type of the annotation.

See also

set_annotation

Assign directly a value to an annotation.

Notes

If the annotation category already exists, a compatible dtype is chosen, that is also able to represent the old values.

array_length()

Get the length of the atom array.

This value is equivalent to the length of each annotation array. For AtomArray it is the same as len(array).

Returns:

lengthint

Length of the array(s).

copy()

Create a deep copy of this object.

Returns:

copy

A copy of this object.

del_annotation(category)

Removes an annotation category.

Parameters:

categorystr

The annotation category to be removed.

equal_annotation_categories(item)

Check, if this object shares equal annotation array categories with the given AtomArray or AtomArrayStack.

Parameters:

itemAtomArray or AtomArrayStack

The object to compare the annotation arrays with.

Returns:

equalitybool

True, if the annotation array names are equal.

equal_annotations(item, equal_nan=True)

Check, if this object shares equal annotation arrays with the given AtomArray or AtomArrayStack.

Parameters:

itemAtomArray or AtomArrayStack

The object to compare the annotation arrays with.

equal_nanbool

Whether to count nan values as equal. Default: True.

Returns:

equalitybool

True, if the annotation arrays are equal.

get_annotation(category)

Return an annotation array.

Parameters:

categorystr

The annotation category to be returned.

Returns:

arrayndarray

The annotation array.

get_annotation_categories()

Return a list containing all annotation array categories.

Returns:

categorieslist

The list containing the names of each annotation array.

get_atom(index)

Obtain the atom instance of the array at the specified index.

The same as array[index], if index is an integer.

Parameters:

indexint

Index of the atom.

Returns:

atomAtom

Atom at position index.

set_annotation(category, array)

Set an annotation array. If the annotation category does not exist yet, the category is created.

Parameters:

categorystr

The annotation category to be set.

arrayndarray

The new value of the annotation category. The size of the array must be the same as the array length.

Notes

If the annotation category already exists, a compatible dtype is chosen, that is able to represent the old and new array values.

Gallery

Enumeration of alkane isomers

Enumeration of alkane isomers