nuri.tools

TM-tools

from nuri.tools import tm as tmtools

This module provides ground-up reimplementation of TM-align algorithm based on the original TM-align code (version 20220412) by Yang Zhang. This implementation aims to reproduce the results of the original code while providing improved user interface and maintainability. Refer to the following paper for details of the algorithm. [1]

All input structures must have only single atom per residue (usually CA atom), as the original TM-align algorithm assumes this.

class nuri.tools.tm.TMAlign

__init__(self: TMAlign, query: object, templ: object, query_ss: str | None = None, templ_ss: str | None = None, *, gapless: bool = True, sec_str: bool = True, local_sup: bool = True, local_with_ss: bool = True, fragment_gapless: bool = True) → None

Prepare TM-align algorithm with the given structures.

Parameters:

query – The query structure, in which each residue is represented by a single atom (usually CA). Must be representable as a 2D numpy array of shape (N, 3), where N is the number of residues.
templ – The template structure, in which each residue is represented by a single atom (usually CA). Must be representable as a 2D numpy array of shape (M, 3), where M is the number of residues.
query_ss – The secondary structure of the query structure. When provided, must be an ASCII string of length N.
templ_ss – The secondary structure of the template structure. When provided, must be an ASCII string of length M.
gapless – Enable gapless threading.
sec_str – Enable secondary structure assignment.
local_sup – Enable local superposition. Note that this is the most expensive initialization method due to the exhaustive pairwise distance calculation. Consider disabling this flag if alignment takes too long.
local_with_ss – Enable local superposition with secondary structure-based alignment.
fragment_gapless – Enable fragment gapless threading.

Raises:

ValueError –

If:

The query or template structure has less than 5 residues.
The secondary structure of the query or template structure has a different length than the structure.
No initialization flag is set.
The initialization fails (for any other reason).

Note

If the secondary structure is not provided, it will be assigned using the approximate secondary structure assignment algorithm defined in the TM-align code. When both sec_str and local_with_ss flags are not set, the secondary structures are ignored.

static from_alignment(query: object, templ: object, alignment: object = None) → TMAlign

Prepare TM-align algorithm with the given structures and user-provided alignment.

Parameters:

query – The query structure, in which each residue is represented by a single atom (usually CA). Must be representable as a 2D numpy array of shape (N, 3), where N is the number of residues.
templ – The template structure, in which each residue is represented by a single atom (usually CA). Must be representable as a 2D numpy array of shape (M, 3), where M is the number of residues.
alignment – Pairwise alignment of the query and template structures. Must be in a form representable as a 2D numpy array of shape (L, 2), in which rows must contain (query index, template index) pairs. If not provided, query and template must have same length and assumed to be aligned in order.

Returns:

A TMAlign object initialized with the given alignment.

Raises:

ValueError –

If:

The query or template structure has less than 5 residues.
The alignment contains out-of-range indices.
Alignment is not provided and the query and template structures have different lengths.
The initialization fails (for any other reason).

Tip

When initialized by this method, the result is equivalent to the “TM-score” program in the TM-tools suite.

Note

Duplicate values in alignment are not checked and may result in invalid alignment.

aligned_pairs(self: TMAlign) → ndarray[numpy.int32]

Get pairwise alignment of the query and template structures.

Returns:: A 2D numpy array of shape (L, 2), where L is the number of aligned pairs. Each row is a (query index, template index) pair.

Tip

This will always return the same alignment once the TMAlign object is created.

Note

Even if the TMAlign object is created with from_alignment(), the returned pairs from this method may not be the same as the input alignment. This is because the TM-align algorithm filters out far-apart pairs when calculating the final alignment.

rmsd(self: TMAlign) → float: The RMSD of the aligned pairs.

score(self: TMAlign, l_norm: int | None = None, *, d0: float | None = None) → tuple[ndarray[numpy.float64], float]

Calculate TM-score using the current alignment.

Parameters:

l_norm – Length normalization factor. If not specified, the length of the template structure is used.
d0 – Distance scale factor. If not specified, calculated based on the length normalization factor.

Returns:

A pair of the transformation tensor and the TM-score of the alignment.

nuri.tools.tm.tm_align(query: object, templ: object, l_norm: int | None = None, query_ss: str | None = None, templ_ss: str | None = None, *, d0: float | None = None, gapless: bool = True, sec_str: bool = True, local_sup: bool = True, local_with_ss: bool = True, fragment_gapless: bool = True) → tuple[ndarray[numpy.float64], float]

Run TM-align algorithm with the given structures and parameters.

Parameters:

query – The query structure, in which each residue is represented by a single atom (usually CA). Must be representable as a 2D numpy array of shape (N, 3), where N is the number of residues.
templ – The template structure, in which each residue is represented by a single atom (usually CA). Must be representable as a 2D numpy array of shape (M, 3), where M is the number of residues.
l_norm – Length normalization factor. If not specified, the length of the template structure is used.
query_ss – The secondary structure of the query structure. When provided, must be an ASCII string of length N.
templ_ss – The secondary structure of the template structure. When provided, must be an ASCII string of length M.
d0 – Distance scale factor. If not specified, calculated based on the length normalization factor.
gapless – Enable gapless threading.
sec_str – Enable secondary structure assignment.
local_sup – Enable local superposition. Note that this is the most expensive initialization method due to the exhaustive pairwise distance calculation. Consider disabling this flag if alignment takes too long.
local_with_ss – Enable local superposition with secondary structure-based alignment.
fragment_gapless – Enable fragment gapless threading.

Returns:

A pair of the transformation tensor and the TM-score of the alignment.

Raises:

ValueError –

If:

The query or template structure has less than 5 residues.
The secondary structure of the query or template structure has a different length than the structure.
No initialization flag is set.
The initialization fails (for any other reason).

Tip

If want to calculate TM-score for multiple l_norm or d0 values, or want more details such as RMSD or aligned pairs, consider using the TMAlign object directly.

Note

If the secondary structure is not provided, it will be assigned using the approximate secondary structure assignment algorithm defined in the TM-align code. When both sec_str and local_with_ss flags are not set, the secondary structures are ignored.