API Reference

SERD.detect

SERD.detect(target: Union[str, Path], surface_representation: Literal['VDW', 'SES', 'SAS'] = 'SES', step: Union[float, int] = 0.6, probe: Union[float, int] = 1.4, vdw: Optional[Union[str, Path]] = None, ignore_backbone: bool = True, nthreads: Optional[int] = None, verbose: bool = False)

Detect solvent-exposed residues of a target biomolecule.

Parameters:

• target (Union[str, pathlib.Path]) – A path to PDB or XYZ file of a target biomolecular structure.

• surface_representation (Literal["VDW", "SES", "SAS"], optional) – Surface representation. Keywords options are VDW (van der Waals), SES (Solvent Excluded Surface) or SAS (Solvent Accessible Surface), by default “SES”.

• step (Union[float, int], optional) – Grid spacing (A), by default 0.6.

• probe (Union[float, int], optional) – Probe size (A) to define SES and SAS representations, by default 1.4.

• vdw (Optional[Union[str, pathlib.Path]], optional) – A path to a van der Waals radii file, by default None. If None, apply the built-in van der Waals radii file: vdw.dat.

• ignore_backbone (bool, optional) – Whether to ignore backbone atoms (C, CA, N, O) when defining interface residues, by default True.

• nthreads (Optional[int], optional) – Number of threads, by default None. If None, the number of threads is os.cpu_count() - 1.

• verbose (bool, optional) – Print extra information to standard output, by default False.

Returns:

residues – A list of solvent-exposed residues.

Return type:

List[List[str]]

Raises:

• TypeError – target must be a string or a pathlib.Path.

• TypeError – surface_representation must be a VDW, SES or SAS.

• TypeError – step must be a positive real number.

• ValueError – step must be a positive real number.

• TypeError – probe must be a non-negative real number.

• ValueError – probe must be a non-negative real number.

• TypeError – vdw must be a string or a pathlib.Path.

• TypeError – nthreads must be a positive integer.

• ValueError – nthreads must be a positive integer.

• TypeError – verbose must be a boolean.

• ValueError – probe must be a positive real number, when SES or SAS is set.

• ValueError – target must be .pdb or .xyz.

Note

The van der Waals radii file defines the radius values for each atom by residue and when not defined, it uses a generic value based on the atom type (see pyKVFinder package).

SERD.g2pdb

SERD.g2pdb(graph: Graph, atomic: ndarray, residues: List[List[str]], fn: Union[str, Path] = 'graph.pdb')

Save a graph to a PDB-formatted file. Each node are represented by the CA atom of the residue and edges are represented by CONECT record.

Parameters:

• graph (networkx.classes.graph.Graph) – A graph of solvent-exposed residues with edges defined by a distance smaller than the cutoff.

• atomic (numpy.ndarray) – A numpy array with atomic data (residue number, chain, residue name, atom name, xyz coordinates and radius) for each atom.

• residues (List[List[str]]) – A list of solvent-exposed residues.

• fn (Union[str, pathlib.Path], optional) – A path to a PDB file, by default “graph.pdb”.

SERD.get_vertices

SERD.get_vertices(atomic: ndarray, probe: Union[float, int] = 1.4, step: Union[float, int] = 0.6) → ndarray

Gets 3D grid vertices.

Parameters:

• atomic (numpy.ndarray) – A numpy array with atomic data (residue number, chain, residue name, atom name, xyz coordinates and radius) for each atom.

• probe (Union[float, int], optional) – Probe size (A), by default 4.0.

• step (Union[float, int], optional) – Grid spacing (A), by default 0.6.

Returns:

vertices – A numpy.ndarray with xyz vertices coordinates (origin, X-axis, Y-axis, Z-axis).

Return type:

numpy.ndarray

SERD.interface

SERD.interface(surface: ndarray, atomic: ndarray, ignore_backbone: bool = True, step: Union[float, int] = 0.6, probe: Union[float, int] = 1.4, nthreads: Optional[int] = None, verbose: bool = False) → List[List[str]]

Identifies the solvent-exposed residues based on a target solvent-exposed surface and atomic information of a biomolecule (residue number, chain identifier, residue name, xyz coordinates, radius).

Parameters:

• surface (numpy.ndarray) –

  Surface points in the 3D grid (surface[nx, ny, nz]). Surface array has integer labels in each positions, that are:

  • -1: solvent points;

  • 0: biomolecule points;

  • 1: solvent-exposed surface points.

  Enclosed regions are considered biomolecule points.

• atomic (numpy.ndarray) – A numpy array with atomic data (residue number, chain, residue name, atom name, xyz coordinates and radius) for each atom.

• ignore_backbone (bool, optional) – Whether to ignore backbone atoms (C, CA, N, O) when defining interface residues, by default True.

• step (Union[float, int], optional) – Grid spacing (A), by default 0.6.

• probe (Union[float, int], optional) – Probe size (A) to define SES and SAS representations, by default 1.4.

• nthreads (Optional[int], optional) – Number of threads, by default None. If None, the number of threads is os.cpu_count() - 1.

• verbose (bool, optional) – Print extra information to standard output, by default False.

Returns:

residues – A list of solvent-exposed residues.

Return type:

List[List[str]]

Raises:

• TypeError – surface must be a numpy.ndarray.

• ValueError – surface has the incorrect shape. It must be (nx, ny, nz).

• TypeError – atomic must be a numpy.ndarray.

• ValueError – atomic has incorrect shape. It must be (n, 8).

• TypeError – ignore_backbone must be a boolean.

• TypeError – step must be a positive real number.

• TypeError – probe must be a non-negative real number.

• ValueError – probe must be a non-negative real number.

• TypeError – nthreads must be a positive integer.

• ValueError – nthreads must be a positive integer.

• TypeError – verbose must be a boolean.

SERD.r2g

SERD.r2g(residues: List[List[str]], atomic: ndarray, selection: Literal['CA', 'CB'] = 'CB', cutoff: Optional[float] = None, intraresidual: bool = False, weighted_edges: bool = False) → Graph

Create a graph from a list of solvent-exposed residues.

Parameters:

• residues (List[List[str]]) – A list of solvent-exposed residues.

• atomic (numpy.ndarray) – A numpy array with atomic data (residue number, chain, residue name, atom name, xyz coordinates and radius) for each atom.

• selection ({"CA", "CB", "all"}, optional) –

  Atomic selection, by default “CB”. Keywords options are:

  • ’CA’: Select alfa-carbon;

  • ’CB’: Select beta-carbon, except for glycine which selects the alfa-carbon;

  • ’all’: Select all atoms, distance between residues are the smallest distance between the atoms of these residues.

• cutoff (Optional[float], optional) – A limit of distance to define an edge between two solvent-exposed residues, by default None. If None, cutoff depends on selection argument. If “CA”, cutoff is 10.0. If “CB”, cutoff is 8.0.

• intraresidual (bool, optional) – Whether to consider intraresidual contacts to create adjacency matrix, by default False.

• weighted_edges (bool, optional) – Whether to include the distances as weight of the edges.

Returns:

A graph of solvent-exposed residues with edges defined by a distance smaller than the cutoff.

Return type:

networkx.classes.graph.Graph

Raises:

ValueError – selection must be CA, CB, or all.

Note

Cutoff for beta-carbon is based on CAPRI round 28. For more details, refer to https://www.ebi.ac.uk/msd-srv/capri/round28/round28.html.

SERD.read_vdw

SERD.read_vdw(fn: Optional[Union[str, Path]] = None) → Dict[str, Dict[str, float]]

Reads van der Waals radii from .dat file.

Parameters:

fn (Optional[Union[str, pathlib.Path]], optional) – A path to a van der Waals radii file, by default None. If None, apply the built-in van der Waals radii file: vdw.dat.

Returns:

vdw – A dictionary containing radii values.

Return type:

Dict[str, Dict[str, float]]

Raises:

• TypeError – fn must be a string or a pathlib.Path.

• ValueError – A line in vdw has incorrect format. The values must be double tab-separated.

• ValueError – A line in vdw has an incorrect radius type for an atom.

Note

The van der Waals radii file defines the radius values for each atom by residue and when not defined, it uses a generic value based on the atom type (see van der Waals file template). The package contains a built-in van der Waals radii file: vdw.dat.

SERD.read_pdb

SERD.read_pdb(fn: Union[str, Path], vdw: Optional[Dict[str, Dict[str, float]]] = None) → ndarray

Reads PDB file into numpy.ndarrays.

Parameters:

• fn (Union[str, pathlib.Path]) – A path to PDB file.

• vdw (Dict[str, Dict[str, float]], optional) – A dictionary containing radii values, by default None. If None, use output of pyKVFinder.read_vdw().

Returns:

atomic – A numpy array with atomic data (residue number, chain, residue name, atom name, xyz coordinates and radius) for each atom.

Return type:

numpy.ndarray

Raises:

TypeError – fn must be a string or a pathlib.Path.

Note

The van der Waals radii file defines the radius values for each atom by residue and when not defined, it uses a generic value based on the atom type. The function by default loads the built-in van der Waals radii file: vdw.dat.

SERD.save

SERD.save(residues: List[List[str]], fn: Union[str, Path] = 'residues.pickle')

Save list of solvent-exposed residues to binary pickle file.

Parameters:

• residues (List[List[str]]) – A list of solvent-exposed residues.

• fn (Union[str, pathlib.Path], optional) – A path to pickle file, by default “residues.pickle”

SERD.save_session

SERD.save_session(target: Union[str, Path], residues: List[List[str]], fn: Union[str, Path] = 'residues.pse')

Save a PyMOL session with the solvent-exposed residues (shown as red sticks) and the target biomolecular structure (shown as cartoon).

Parameters:

• target (Union[str, pathlib.Path]) – A path to PDB or XYZ file of a target biomolecular structure.

• residues (List[List[str]]) – A list of solvent-exposed residues.

• fn (Union[str, pathlib.Path], optional) – A path to a PyMOL session file, by default “residues.pse”.

SERD.surface

SERD.surface(atomic: ndarray, surface_representation: Literal['VDW', 'SES', 'SAS'] = 'SES', step: Union[float, int] = 0.6, probe: Union[float, int] = 1.4, nthreads: Optional[int] = None, verbose: bool = False) → ndarray

Defines the solvent-exposed surface of a target biomolecule in a 3D grid.

Parameters:

• atomic (numpy.ndarray) – A numpy array with atomic data (residue number, chain, residue name, atom name, xyz coordinates and radius) for each atom.

• surface_representation (Literal["VDW", "SES", "SAS"], optional) – Surface representation. Keywords options are VDW (van der Waals surface), SES (Solvent Excluded Surface) or SAS (Solvent Accessible Surface), by default “SES”.

• step (Union[float, int], optional) – Grid spacing (A), by default 0.6.

• probe (Union[float, int], optional) – Probe size (A) to define SES and SAS representations, by default 1.4.

• nthreads (Optional[int], optional) – Number of threads, by default None. If None, the number of threads is os.cpu_count() - 1.

• verbose (bool, optional) – Print extra information to standard output, by default False.

Returns:

surface – Surface points in the 3D grid (surface[nx, ny, nz]). Surface array has integer labels in each positions, that are:

• -1: solvent points;

• 0: biomolecule points;

• 1: solvent-exposed surface points.

Enclosed regions are considered biomolecule points.

Return type:

numpy.ndarray

Raises:

• TypeError – atomic must be a numpy.ndarray.

• ValueError – atomic has incorrect shape. It must be (n, 8).

• TypeError – surface_representation must be a VDW, SES or SAS.

• TypeError – step must be a positive real number.

• ValueError – step must be a positive real number.

• TypeError – probe must be a non-negative real number.

• ValueError – probe must be a non-negative real number.

• TypeError – nthreads must be a positive integer.

• ValueError – nthreads must be a positive integer.

• TypeError – verbose must be a boolean.

• ValueError – probe must be a positive real number, when SES or SAS is set.