CellList#

class biotite.structure.CellList(atom_array, cell_size, periodic=False, box=None, selection=None)[source]#

Bases: object

This class enables the efficient search of atoms in vicinity of a defined location.

This class stores the indices of an atom array in virtual “cells”, each corresponding to a specific coordinate interval. If the atoms in vicinity of a specific location are searched, only the atoms in the relevant cells are checked. Effectively this decreases the operation time for finding atoms with a maximum distance to given coordinates from O(n) to O(1), after the CellList has been created. Therefore a CellList saves calculation time in those cases, where vicinity is checked for multiple locations.

Parameters:
atom_arrayAtomArray or ndarray, dtype=float, shape=(n,3)

The AtomArray to create the CellList for. Alternatively the atom coordinates are accepted directly. In this case box must be set, if periodic is true.

cell_sizefloat

The coordinate interval each cell has for x, y and z axis. The amount of cells depends on the range of coordinates in the atom_array and the cell_size.

periodicbool, optional

If true, the cell list considers periodic copies of atoms. The periodicity is based on the box attribute of atom_array.

boxndarray, dtype=float, shape=(3,3), optional

If provided, the periodicity is based on this parameter instead of the box attribute of atom_array. Only has an effect, if periodic is True.

selectionndarray, dtype=bool, shape=(n,), optional

If provided, only the atoms masked by this array are stored in the cell list. However, the indices stored in the cell list will still refer to the original unfiltered atom_array.

Examples

>>> cell_list = CellList(atom_array, cell_size=5)
>>> near_atoms = atom_array[cell_list.get_atoms(np.array([1,2,3]), radius=7.0)]
class Result#

Bases: object

The desired type of result to be returned by some CellList methods.

  • MAPPING - An (q, k) array mapping each query coordinate q to the indices of its neighbors. Since the coordinates may have different amounts of adjacent atoms, trailing -1 values are used to indicate nonexisting indices. If only a single query coordinate is provided, the return value has shape (k,).

  • MASK - A boolean mask of shape (q, n) where the value at (i, j) is True if the query coordinate i and atom j are neighbors. If only a single query coordinate is provided, the return value has shape (n,).

  • PAIRS - An array of shape (k, 2) where each row contains the (query_idx, atom_idx) tuple of a found neighboring atom. This is basically a sparse representation of the MASK. If only a single query coordinate is provided, the return value has shape (k,), equivalent to MAPPING.

Examples

>>> # Create a CellList for a small molecule
>>> from biotite.structure.info import residue
>>> atoms = residue("ALA")
>>> cell_list = CellList(atoms, cell_size=2)
>>> # Demonstrate results for both, single and multiple query coordinates
>>> single_coord = atoms.coord[0]
>>> multiple_coords = atoms.coord[:2]
>>> # MAPPING: indices of neighboring atoms, -1 indicates padding values to be ignored
>>> print(cell_list.get_atoms(single_coord, radius=2, result_format=CellList.Result.MAPPING))
[6 1 0 7]
>>> print(cell_list.get_atoms(multiple_coords, radius=2, result_format=CellList.Result.MAPPING))
[[ 6  1  0  7 -1]
 [ 2  1  0  4  8]]
>>> # MASK: boolean mask indicating neighbors
>>> print(cell_list.get_atoms(single_coord, radius=2, result_format=CellList.Result.MASK))
[ True  True False False False False  True  True False False False False
 False]
>>> print(cell_list.get_atoms(multiple_coords, radius=2, result_format=CellList.Result.MASK))
[[ True  True False False False False  True  True False False False False
  False]
 [ True  True  True False  True False False False  True False False False
  False]]
>>> # PAIRS: (query_idx, atom_idx) tuples
>>> print(cell_list.get_atoms(single_coord, radius=2, result_format=CellList.Result.PAIRS))
[6 1 0 7]
>>> print(cell_list.get_atoms(multiple_coords, radius=2, result_format=CellList.Result.PAIRS))
[[0 6]
 [0 1]
 [0 0]
 [0 7]
 [1 2]
 [1 1]
 [1 0]
 [1 4]
 [1 8]]
create_adjacency_matrix(threshold_distance)#

Create an adjacency matrix for the atoms in this cell list.

An adjacency matrix depicts which atoms i and j have a distance lower than a given threshold distance. The values in the adjacency matrix m are m[i,j] = True if distance(i,j) <= threshold else False.

Parameters:
threshold_distancefloat

The threshold distance. All atom pairs that have a distance lower than or equal to this value are indicated by True values in the resulting matrix.

Returns:
matrixndarray, dtype=bool, shape=(n,n)

An n x n adjacency matrix. If a selection was given to the constructor of the CellList, the rows and columns corresponding to atoms that are not masked by the selection have all elements set to False.

Notes

The highest performance is achieved when the cell_size is equal to the threshold_distance. However, this is purely optional: the resulting adjacency matrix is the same for every cell_size.

Although the adjacency matrix should be symmetric in most cases, it may occur that m[i,j] != m[j,i] when distance(i,j) is very close to the threshold_distance due to numerical errors. The matrix can be symmetrized with numpy.maximum(m, m.T).

Examples

Create adjacency matrix for CA atoms in a structure:

>>> atom_array = atom_array[atom_array.atom_name == "CA"]
>>> cell_list = CellList(atom_array, 5)
>>> matrix = cell_list.create_adjacency_matrix(5)
get_atoms(coord, radius, as_mask=False, result_format=CellList.Result.MAPPING)#

Find atoms with a maximum distance from given coordinates.

Parameters:
coordndarray, dtype=float, shape=(3,) or shape=(m,3)

One or more coordinates around which the atoms are searched.

radiusfloat or ndarray, shape=(n,), dtype=float

The radius around coord, in which the atoms are searched, i.e. all atoms within radius distance to coord are returned. Either a single radius can be given as scalar, or individual radii for each position in coord can be provided as ndarray.

as_maskbool, optional

Deprecated: Use result_format=CellList.Result.MASK instead. If true, the result is returned as boolean mask instead of an index array.

result_formatCellList.Result, optional

The format of the result. See CellList.Result for options. Default is CellList.Result.MAPPING.

Returns:
resultndarray

The result format depends on result_format. See CellList.Result for details.

See also

get_atoms_in_cells

Notes

In case of a CellList with periodic set to True: If more than one periodic copy of an atom is within the threshold radius, the returned indices array may contain the corresponding index multiple times. Use numpy.unique() if this is undesirable.

Examples

Get adjacent atoms for a single position:

>>> cell_list = CellList(atom_array, 3)
>>> pos = np.array([1.0, 2.0, 3.0])
>>> indices = cell_list.get_atoms(pos, radius=2.0)
>>> print(indices)
[102 104 112]
get_atoms_in_cells(coord, cell_radius=1, as_mask=False, result_format=CellList.Result.MAPPING)#

Find atoms with a maximum cell distance from given coordinates.

Instead of using the radius as maximum Euclidean distance to the given coordinates, the radius is measured as the number of cells: A radius of 0 means that only the atoms in the same cell as the given coordinates are considered. A radius of 1 means that the atom indices from this cell and the 26 surrounding cells are returned, and so forth. This is more efficient than get_atoms().

Parameters:
coordndarray, dtype=float, shape=(3,) or shape=(m,3)

One or more coordinates around which the atoms are searched.

cell_radiusint or ndarray, shape=(n,), dtype=int, optional

The radius around coord (in number of cells), in which the atoms are searched. This does not correspond to the Euclidean distance used in get_atoms(). In this case, all atoms in the cell corresponding to coord and in adjacent cells are returned. Either a single radius can be given as scalar, or individual radii for each position in coord can be provided as ndarray. By default, atoms are searched in the cell of coord and directly adjacent cells (cell_radius=1).

as_maskbool, optional

Deprecated: Use result_format=CellList.Result.MASK instead. If true, the result is returned as boolean mask instead of an index array.

result_formatCellList.Result, optional

The format of the result. See CellList.Result for options. Default is CellList.Result.MAPPING.

Returns:
resultndarray

The result format depends on result_format. See CellList.Result for details.

See also

get_atoms

Notes

In case of a CellList with periodic set to True: If more than one periodic copy of an atom is within the threshold radius, the returned indices array may contain the corresponding index multiple times. Use numpy.unique() if this is undesirable.

On this page
Edit on GitHub
Show Source