Structure Alignment Data Model

The `AFPChain` data structure was designed to store pairwise structural

alignments. The class functions as a bean, and contains many variables

used internally by the alignment algorithms implemented in biojava.

The residue equivalencies of the alignment (EQRs) are described in the optimal

alignment variable, a triple array of integers, where the indices stand for:

int[][][] optAln = afpChain.getOptAln();

int residue = optAln[block][chain][eqr];

* **block**: the blocks divide the alignment into different parts. The

division can be due to non-topological rearrangements (e.g. circular

permutations) or due to flexible parts (e.g. domain switch). There can

be any number of blocks in a structural alignment, defined by the structure

alignment algorithm.

* **chain**: in a pairwise alignment there are only two chains, or structures.

* **eqr**: EQR stands for equivalent residue position, i.e. the alignment

position. There are as many positions (EQRs) in a block as the length of

the alignment block, and their number is equal for any of the two chains in

the same block.

In each entry (combination of the three indices described above) an integer

is stored, which corresponds to the residue index in the specified chain, i.e.

the index in the Atom array of the chain. In between the same block, the stored

integers (residues) are always in increasing order.

As an overview, the `AFPChain` data model:

* Only supports **pairwise alignments**, i.e. two chains or structures aligned.

* Can support **flexible alignments** and **non-topological alignments**.

However, their combinatation (a flexible alignment with topological rearrangements)

can not be represented, because the blocks mean either one or the other.

* Can not support **non-sequential alignments**, or they would require a new block

for each EQR, because sequentiality of the residues is assumed inside each block.

Since BioJava 4.1.0, a new data model is available to store structure alignments.

The `MultipleAlignment` data structure is a general model that supports any of the

following properties, and any combination:

* **Multiple structures**: the model is no longer restricted to pairwise alignments.

* **Non-topological alignments**: such as circular permutations or domain rearrangements.

* **Flexible alignments**: parts of the alignment with different superposition

transformation.

In addtition, the data structure is not limited in the number and types of scores

it can store, because the scores are stored in a key:value fashion, as it will be

described later.

The biggest difference with `AFPChain` is that the `MultipleAlignment` data

structure is object oriented.

The hierarchy of sub-objects is represented below:

<pre>

MultipleAlignmentEnsemble

|

MultipleAlignment(s)

|

BlockSet(s)

|

Block(s)

</pre>

* **MultipleAlignmentEnsemble**: the ensemble is the top level of the hierarchy.

As a top level, it stores information regarding creation properties (algorithm,

version, creation time, etc.) and the structures involved in the alignment (Atoms,

structure identifiers, etc.). It contains a collection of `MultipleAlignment` that

share the same properties stored in the ensemble. This construction allows the

storage of alternative alignments inside the same data structure.

* **MultipleAlignment**: the `MultipleAlignment` stores the core information of a

multiple structure alignment. It is designed to be the return type of the multiple

structure alignment algorithms. The object contains a collection of `BlockSet` and

it is linked to its parent `MultipleAlignmentEnsemble`.

* **BlockSet**: the `BlockSet` stores a flexible part of a multiple structure

alignment. A flexible part needs the residue equivalencies involved, contained in

a collection of `Block`, and a transformation matrix for every structure that

describes the 3D superposition of all structures. It is linked to its parent

`MultipleAlignment`.

* **Block**: the `Block` stores the aligned positions (equivalent residues) of a

`BlockSet` that are in sequentially increasing order. Each `Block` represents a

sequential part of a non-topological alignment, if more than one `Block` is present.

It is linked to its parent `BlockSet`.

In the `MultipleAlignment` data structure the aligned residues are stored in a

double List for every `Block`. The indices of the double List are the following:

List<List<Integer>> optAln = block.getAlnRes();

Integer residue = optAln.get(chain).get(eqr);

The indices mean the same as in the optimal alignment of the `AFPChain`, just to

remember them:

* **chain**: chain or structure index.

* **eqr**: EQR stands for equivalent residue position, i.e. the alignment

position. There are as many positions (EQRs) in a block as the length of

the alignment block, and their number is equal for any of the chains in

the same block.

As in `AFPChain`, each entry (combination of the two indices described above)

is an Integer that corresponds to the residue index in the specified chain, i.e.

the index in the Atom array of the chain. Caution has to be taken in the code,

because a `MultipleAlignment` can contain gaps, which are represented as `null`

in the List entries.

The conversion from an `AFPChain` to a `MultipleAlignment` is possible trough the

ensemble constructor. An example on how to do it programatically is below:

There is no method to convert from a `MultipleAlignment` to an `AFPChain`, because

the first representation supports any number of structures, while the second is

only supporting pairwise alignments. However, the conversion can be done with some

lines of code if needed (instantiate a new `AFPChain` and copy one by one the

properties that can be represented from the `MultipleAlignment`.