biotite.structure.BondList

class biotite.structure.BondList(atom_count, bonds=None)

Bases: biotite.copyable.Copyable

A bond list stores indices of atoms (usually of an AtomArray or AtomArrayStack) that form chemical bonds together with the type (or order) of the bond.

Internally the bonds are stored as n x 3 ndarray. For each row, the first column specifies the index of the first atom, the second column the index of the second atom involved in the bond. The third column stores an integer that is interpreted as member of the the BondType enum, that specifies the order of the bond.

When indexing a BondList, the index is not forwarded to the internal ndarray. Instead the indexing behavior is consistent with indexing an AtomArray or AtomArrayStack: Bonds with at least one atom index that is not covered by the index are removed, atom indices that occur after an uncovered atom index move up. Effectively, this means that after indexing an AtomArray and a BondList with the same index, the atom indices in the BondList will still point to the same atoms in the AtomArray before and after indexing. If a BondList is indexed with single integer as index, get_bonds() will be called with the index as parameter.

The same consistency applies to adding BondList instances via the ‘+’ operator: The atom indices of the second BondList are increased by the atom count of the first BondList.

Parameters
atom_countint

A positive integer, that specifies the amount of atoms the BondList refers to (usually the length of an atom array (stack)). Effectively, this value is the exclusive maximum for the indices stored in the BondList.

bondsndarray, shape=(n,2) or shape=(n,3), dtype=int, optional

This array contains the indices of atoms which are bonded: For each row, the first column specifies the first atom, the second row the second atom involved in a chemical bond. If an n x 3 array is provided, the additional column specifies a BondType instead of BondType.ANY. By default, the created BondList is empty.

Notes

When initially providing the bonds as ndarray, the input is sanitized: Redundant bonds are removed, and each bond entry is sorted so that the lower one of the two atom indices is in the first column.

Examples

Construct a BondList, where a central atom (index 1) is connected to three other atoms (index 0, 3 and 4):

>>> bond_list = BondList(5, np.array([(1,0),(1,3),(1,4)]))
>>> print(bond_list)
[[0 1 0]
 [1 3 0]
 [1 4 0]]

Remove the first atom (index 0) via indexing: The bond containing index 0 is removed, since the corresponding atom does not exist anymore. Since all other atoms move up in their position, the indices in the bond list are decreased by one:

>>> bond_list = bond_list[1:]
>>> print(bond_list)
[[0 2 0]
 [0 3 0]]
add_bond(index1, index2, bond_type=BondType.ANY)

Add a bond to the BondList.

If the bond is already existent, only the bond type is updated.

Parameters
index1, index2int

The indices of the atoms to create a bond for.

bond_typeBondType or int, optional

The type of the bond. Default is BondType.ANY.

as_array

Obtain a copy of the internal ndarray.

Returns
arrayndarray, shape=(n,3), dtype=np.uint32

Copy of the internal ndarray. For each row, the first column specifies the index of the first atom, the second column the index of the second atom involved in the bond. The third column stores the BondType.

copy(self)

Create a deep copy of this object.

Returns
copy

A copy of this object.

get_atom_count

Get the atom count.

Returns
atom_countint

The atom count.

get_bond_count

Get the amount of bonds.

Returns
bond_countint

The amount of bonds. This is equal to the length of the internal ndarray containing the bonds.

get_bonds(atom_index)

Obtain the indices of the atoms bonded to the atom with the given index as well as the corresponding bond types.

Parameters
atom_indexint

The index of the atom to get the bonds for.

Returns
bondsnp.ndarray, dtype=np.uint32

The indices of connected atoms.

bond_typesnp.ndarray, dtype=np.uint8

Array of integers, interpreted as BondType instances. This array specifies the type (or order) of the bonds to the connected atoms.

Examples

>>> bond_list = BondList(5, np.array([(1,0),(1,3),(1,4)]))
>>> bonds, types = bond_list.get_bonds(1)
>>> print(bonds)
[0 3 4]
merge(bond_list)

Merge the this instance with another BondList in a new object.

The internal ndarray instances containg the bonds are simply concatenated and the new atom count is the maximum atom count of the merged bond lists.

Parameters
bond_listBondList

The bonds in bond_list are removed from this instance.

Returns
bond_listBondList

The merged BondList.

Notes

This is not equal to using ‘+’ operator.

Examples

>>> bond_list1 = BondList(3, np.array([(0,1),(1,2)]))
>>> bond_list2 = BondList(5, np.array([(2,3),(3,4)]))
>>> merged_list = bond_list1.merge(bond_list2)
>>> print(merged_list.get_atom_count())
5
>>> print(merged_list)
[[0 1 0]
 [1 2 0]
 [2 3 0]
 [3 4 0]]
offset_indices(offset)

Increase all atom indices in the BondList by the given offset.

Implicitly this increases the atom count.

Parameters
offsetint

The atom indices are increased by this value. Must be positive.

Examples

>>> bond_list = BondList(5, np.array([(1,0),(1,3),(1,4)]))
>>> print(bond_list)
[[0 1 0]
 [1 3 0]
 [1 4 0]]
>>> bond_list.offset_indices(2)
>>> print(bond_list)
[[2 3 0]
 [3 5 0]
 [3 6 0]]
remove_bond(index1, index2)

Remove a bond from the BondList.

If the bond is not existent in the BondList, nothing happens.

Parameters
index1, index2int

The indices of the atoms whose bond should be removed.

remove_bonds(bond_list)

Remove multiple bonds from the BondList.

All bonds present in bond_list are removed from this instance. If a bond is not existent in this instance, nothing happens. Only the bond indices, not the bond types, are relevant for this.

Parameters
bond_listBondList

The bonds in bond_list are removed from this instance.