selection

A module containing the Selection class and related functions/classes.

Summary

Classes:

Selection

A class for representing a selection.

SelectionTransformer

A class for transforming a Lark parse tree.

SelectionVisitor

A class for visiting a Lark parse tree and returning the indices of parsed selection.

Reference

class Selection(
selection_object: SelectionCompatible = None,
)[source]

Bases: object

A class for representing a selection.

If the selection object is a Selection object, the selection is copied.

There are several ways to create a selection:

  • None: all atoms are selected

  • Atom: the given atom is selected

  • Element: all atoms with the given element type are selected

  • Atoms: all atoms in the given list are selected

  • Elements: all atoms with the given element types are selected

  • Np1DIntArray: the atoms with the given indices are selected

  • List[str]: all atoms with the given atom type names are selected

  • str: the given string is parsed and the atoms selected by the

selection are selected

This string will be parsed based on a Lark grammar. Which is defined as follows:

  • simple word containing only letters and numbers: the

atom type with the given name is selected - <integer>: the atom with the given index is selected - <integer1>..<integer2>: the indices from integer1 to integer2 are selected - <integer1>-<integer2>: the indices from integer1 to integer2 are selected - <integer1>..<integer2>..<integer3>: the indices from integer1 to integer3 with a step size of integer3 are selected - atom(<atomtype>, <atomic_number>): the atom with the given atom type and atomic number is selected - atom(<atomtype>, <element_symbol>): the atom with the given atom type and element symbol is selected - elem(<atomic_number>): all atoms with the given element type are selected - elem(<element_symbol>): all atoms with the given element type are selected - *: all atoms are selected (same as ‘all’), useful if only few atoms should be excluded

All of the above statements can be combined with the following operators:

  • ‘,’: the union of the two statements is selected, meaning that

the atoms selected by the first statement and the atoms selected by the second statement are selected - ‘&’: the intersection of the two statements is selected, meaning that only the atoms selected by both statements are selected - ‘|’: the set difference of the two statements is selected, meaning that only the atoms selected by the first statement are selected, which are not selected by the second statement

The operators are evaluated in the following order: ‘|’ -> ‘&’ -> ‘,’ This means that the ‘,’ operator has the lowest precedence and the ‘|’ operator has the highest precedence and therefore binds the strongest.

Additionally, parentheses can be used to group statements and change the order of evaluation.

Notes

The atom counting always starts with 0!

Parameters:

selection_object (SelectionCompatible, optional) – The object to create the selection from.

__repr__() → str[source]

Returns the string representation of the selection object.

Returns:

The string representation of the selection object.

Return type:

str

__str__() → str[source]

Returns the string representation of the selection object.

Returns:

The string representation of the selection object.

Return type:

str

select(
topology: Topology,
use_full_atom_info: bool = False,
) → Np1DIntArray[source]

Returns the indices of the atoms selected by the selection object.

If the selection_object is None all atoms are selected. With the parameter use_full_atom_info the selection can be performed based on the full atom information (i.e. atom type names and element type information). If use_full_atom_info is False, the selection is performed based on the element type information only.

Parameters:

  • topology (Topology) – The topology to get the indices from.

  • use_full_atom_info (bool, optional) – Whether to use the full atom information, by default False

Returns:

The indices of the atoms selected by the selection object.

Return type:

Np1DIntArray

logger = <CustomLogger PQAnalysis.Selection (INFO)>
class SelectionCompatible
A type variable for the Selection class.
It can be used to specify the type of the selection object.
The following types are supported:
- str: the given string is parsed and the atoms selected by the selection are selected
- Atom: the given atom is selected
- Element: all atoms with the given element type are selected
- Atoms: all atoms in the given list are selected
- Elements: all atoms with the given element types are selected
- Np1DIntArray: the atoms with the given indices are selected
- List[str]: all atoms with the given atom type names are selected
- Selection: the given selection is copied
- None: all atoms are selected

alias of TypeVar(‘SelectionCompatible’, str, PQAnalysis.core.Atom, list[PQAnalysis.core.Atom], PQAnalysis.core.Element, list[PQAnalysis.core.Element], ~PQAnalysis.types.Np1DIntArray, list[str], PQAnalysis.topology.Selection, None)

class SelectionTransformer(
topology=Topology with 0 atoms and 0 residues and 0 unique residues.,
visit_tokens=False,
use_full_atom_info=False,
)[source]

Bases: Transformer

A class for transforming a Lark parse tree.

Parameters:

  • Transformer (Transformer) – The type of the Transformer class to inherit from.

  • visit_tokens (bool, optional) – Whether to visit the tokens, by default False

  • topology (Topology) – The topology to get the indices from.

  • use_full_atom_info (bool, optional) – Whether to use the full atom information, by default False

INT(
items: list[Token] | Token,
) → int[source]

Returns the integer of the given token.

Parameters:

items (List[Token] | Token) – The token to get the integer of.

Returns:

The integer of the given token.

Return type:

int

UNSIGNED_INT(
items: Token | list[Token],
) → int[source]

Returns the unsigned integer of the given token.

Parameters:

items (List[Token] | Token) – The token to get the unsigned integer of.

Returns:

The unsigned integer of the given token.

Return type:

int

all(
_,
) → Np1DIntArray[source]

Returns all indices.

Returns:

The indices of the all Token.

Return type:

Np1DIntArray

and_statement(
items: Any,
) → Np1DIntArray[source]

Returns the indices of the and_statement Token.

Parameters:

items (List[Np1DIntArray]) – The indices to get the indices of.

Returns:

The indices of the and_statement Token.

Return type:

Np1DIntArray

atom(
items: Any,
) → Np1DIntArray[source]

Returns the indices of the given atom.

Parameters:

items (Any) – The atom to get the indices of.

Returns:

The indices of the given atom.

Return type:

Np1DIntArray

atomtype(
items: Any,
) → Np1DIntArray[source]

Returns the indices of the atoms with the given atom type name.

Parameters:

items (Any) – The atom type name to get the indices of.

Returns:

The indices of the atoms with the given atom type name.

Return type:

Np1DIntArray

element(
items: Any,
) → Np1DIntArray[source]

Returns the indices of the given element type.

Parameters:

items (Any) – The element type to get the indices of.

Returns:

The indices of the given element type.

Return type:

Np1DIntArray

index(
items: list[int],
) → Np1DIntArray[source]

Returns the given index as an array.

Parameters:

items (List[int]) – The index to get the indices of.

Returns:

The indices of the index Token.

Return type:

Np1DIntArray

indices(
items: list[int],
) → Np1DIntArray[source]

Returns a range of indices based on the given indices.

if two indices are given, a range from the first index to the second index is returned. if three indices are given, a range from the first index to the third index with a step size of the second index is returned.

Parameters:

items (List[int]) – The indices to get the indices of.

Returns:

The indices of the indices Token.

Return type:

Np1DIntArray

Raises:

PQValueError – If the indices Token has more than 3 items. Should never be reached.

integer(
items: list[Token],
) → int[source]

Returns the integer of the given token.

Parameters:

items (List[Token]) – The token to get the integer of.

Returns:

The integer of the given token.

Return type:

int

letters(
items: list[Token],
) → str[source]

Returns the letters of the given token.

Parameters:

items (List[Token]) – The token to get the letters of.

Returns:

The letters of the given token.

Return type:

str

or_statement(
items: Any,
) → Np1DIntArray[source]

Returns the indices of the or_statement Token.

Parameters:

items (List[Np1DIntArray]) – The indices to get the indices of.

Returns:

The indices of the or_statement Token.

Return type:

Np1DIntArray

residue(
items: Any,
) → Np1DIntArray[source]

Returns the indices of the given residue name.

Parameters:

items (Any) – The residue name to get the indices of.

Returns:

The indices of the given residue name.

Return type:

Np1DIntArray

residue_number(
items: Any,
) → Np1DIntArray[source]

Returns the indices of the given residue number.

Parameters:

items (Any) – The residue number to get the indices of.

Returns:

The indices of the given residue number.

Return type:

Np1DIntArray

unsigned_integer(
items: list[Token],
) → int[source]

Returns the unsigned integer of the given token.

Parameters:

items (List[Token]) – The token to get the unsigned integer of.

Returns:

The unsigned integer of the given token.

Return type:

int

without_statement(
items: Any,
) → Np1DIntArray[source]

Returns the indices of the the first item without the indices of all other items.

Parameters:

items (List[Np1DIntArray]) – The indices to get the indices of.

Returns:

The indices of the given without statement Token.

Return type:

Np1DIntArray

word(
items: list[Token],
) → str[source]

Returns the word of the given token.

Parameters:

items (List[Token]) – The token to get the word of.

Returns:

The word of the given token.

Return type:

str

class SelectionVisitor[source]

Bases: Visitor

A class for visiting a Lark parse tree and returning the indices of parsed selection.

Parameters:

  • Visitor (Visitor) – The type of the Visitor class to inherit from.

  • topology (Topology) – The topology to get the indices from.

  • use_full_atom_info (bool, optional) – Whether to use the full atom information, by default False

expression(
tree: Tree,
) → Np1DIntArray[source]

Visits the given tree and returns the indices of the parsed selection.

Parameters:

tree (Tree) – The tree to visit.

Returns:

The indices of the parsed selection.

Return type:

Np1DIntArray

visit(
tree: Tree,
) → Np1DIntArray[source]

Visits the given tree and returns the indices of the parsed selection.

Parameters:

tree (Tree) – The tree to visit.

Returns:

The indices of the parsed selection.

Return type:

Np1DIntArray