linktetrado 1.0.0
Detect multimeric motifs.

# Project description

LinkTetrado is algorithm designed for the identification and classification
of multimeric nucleotide assemblies in nucleic acid structures.
LinkTetrado automatically identifies nucleotides interacting with tetrads in
a planar arrangement, allowing for the detection of pentads, hexads, heptads, octads, and beyond.
It analyzes nucleic acid 3D structures, accepting both PDB and mmCIF file formats.
It leverages the ElTetrado engine to extract detailed structural information about
base pairs and tetrads in an input structure. Next, it searches the space in the vicinity
of tetrads for possible nucleotides that could interact with the tetrads.

# Polyadic motifs

Polyadic motifs - such as triads (3 bases), tetrads (4), pentads (5), hexads (6), 
heptads (7), and octads (8) - are formed when three or more nucleotides interact through
hydrogen bonding, typically through their Hoogsteen or sugar edges, resulting in stable, 
ring-like networks where each base generally forms bonds with two adjacent bases. 
These polyadic motifs play a crucial role in enhancing the stability and structural 
complexity of nucleic acids and are involved in essential processes, including gene 
regulation and molecular recognition. The figure below illustrates schematic 
representations of example polyadic motifs in a cut, top down 3D visualization 
and a simple 2D graph.


![Polyad Example](https://github.com/michal-zurkowski/linktetrado/blob/main/polyad-examples.png?raw=true)
Example polyadic motifs of different orders and their schematic representations:
(A) pentad (5 nucleotides), (B) hexad (6 nucleotides), (C) heptad (7 nucleotides), and
(D) octad (8 nucleotides). In the 3D models (top row), nucleotides forming the polyads
are shown in color, coded by nucleotide type: green for guanine, blue for uracil or
thymine, and red for adenine. Green thus highlights the guanine tetrad core.

# Installation

Please run:

    pip install linktetrado

# Dependencies

The project is written in Python 3.8+ and requires
[NumPy](https://numpy.org/), and 
[ElTetrado](https://github.com/tzok/eltetrado) (Zok _et al._, 2022;
Popenda _et al._, 2020; Zok _et al._, 2020).

LinkTetrado parses the output of
[ElTetrado](https://github.com/tzok/eltetrado). It can also process PDB or
PDBx/mmCIF files which will be first analyzed internally with ElTetrado.

# Usage

    usage: linktetrado [-h] [-i INPUT] [--print-eltetrado]
                       [--tilt-max TT_MAX] [--tilt-avg TT_AVG]
                       [--height-max HT_MAX] [--height-avg HT_AVG]
                       [--dist-in-max DT_INMAX] [--dist-out-max DT_OUTMAX]
                       [--lax-order] [-m MODEL]
                       [--stacking-mismatch STACKING_MISMATCH] [--strict]
                       [--no-reorder]

    options:
      -h, --help            show this help message and exit
      -i INPUT, --input INPUT
                            path to input PDB, PDBx/mmCIF file.
      --print-eltetrado     (optional) should ElTetrado analysis output also
                            be provided alongside multimer analysis.
      --tilt-max TT_MAX     (optional) maximum tilt in degrees between
                            potential polyad candidate nucleotide and all
                            tetrad nucleotides [default=55]
      --tilt-avg TT_AVG     (optional) average tilt in degrees between
                            potential polyad candidate nucleotide and all
                            tetrad nucleotides [default=45]
      --height-max HT_MAX   (optional) maximum height difference in Angstrem
                            between between potential polyad candidate
                            nucleotide and all tetrad nucleotides
                            [default=3.7]
      --height-avg HT_AVG   (optional) average height difference in Angstrem
                            between between potential polyad candidate
                            nucleotide and all tetrad nucleotides
                            [default=3.15]
      --dist-in-max DT_INMAX
                            (optional) maximum distance in Angstrem between
                            inner atoms between potential polyad candidate
                            nucleotide and all tetrad nucleotides
                            [default=13.75]
      --dist-out-max DT_OUTMAX
                            (optional) maximum distance in Angstrem between
                            outer atoms between potential polyad candidate
                            nucleotide and all tetrad nucleotides
                            [default=12.5]
      --lax-order           (optional) adjusts the algorithm’s filtering
                            mode, enabling the detection of polyads with
                            varying orders within a single stack
      -m MODEL, --model MODEL
                            (optional, ElTetrado) model number to process
      --stacking-mismatch STACKING_MISMATCH
                            a perfect tetrad stacking covers 4 nucleotides;
                            this option can be used with value 1 or 2 to
                            allow this number of nucleotides to be non-
                            stacked with otherwise well aligned tetrad
                            [default=2]
      --strict              nucleotides in tetrad are found when linked only
                            by cWH pairing
      --no-reorder          chains of bi- and tetramolecular quadruplexes
                            should be reordered to be able to have them
                            classified; when this is set, chains will be
                            processed in original order, which for
                            bi-/tetramolecular means that they will likely be
                            misclassified; use with care!


# Examples

The repository contains 4 example structures that contain pentad, hexad, heptad and octad
motifs as well as the expected default output from the program that is expected for each of them.
The examples include structures 1JJP (pentad), 1EEG (hexad), 1oz8 (heptad), 1n7a (octad). 

# Bibliography

<div id="refs" class="references csl-bib-body">

1.  Zok T, Popenda M, Szachniuk M (2020) ElTetrado: a tool for
    identification and classification of tetrads and quadruplexes, BMC
    Bioinformatics 21:40 (doi:10.1186/s12859-020-3385-1).

2.  Popenda M, Miskiewicz J, Sarzynska J, Zok T, Szachniuk M (2020)
    Topology-based classification of tetrads and quadruplex structures,
    Bioinformatics 36(4):1129-1134 (doi:10.1093/bioinformatics/btz738).

3.  Zok T, Kraszewska N, Miskiewicz J, Pielacinska P, Zurkowski M,
    Szachniuk M (2022) ONQUADRO: a database of experimentally determined
    quadruplex structures, Nucleic Acids Research 50(D1):D253-D258
    (doi:10.1093/nar/gkab1118).

</div>