Matrices are commonly used in molecular sequence analysis to compare seque nce characters at the same position in two or more aligned sequences.

Matrix objects are created by reading a matrix local data file, either through ACD (where the user has a choice of files), or by directly reading a named file where the filename is fixed.

EMBOSS includes sets of comparison matrix files in the data directory which can be used as examples when creating new files.

Matrix objects are in two very similar forms, using integers (AjPMatrix) for speed, and floating point numbers (AjPMatrixf) for flexibility. Both types include a set of column labels (usually sequence characters), and a set of row labels which usually matches the column labels (asymmetric matrices are used in some applications). For rows and columns there is also a matrix size value. The numbers in the data file become a two-dimensional table of comparison values.

For sequence alignments functions are provided to use a matrix object to align two sequences.

Applications that analyse sequence alignments, for example prettyplot, can directly use the conversion table and character codes in a matrix to look up comparison scores using an AjPSeqcvt object.

AJAX library files for handling matrices are listed in the table (Table 6.15, “AJAX Library Files for Handling Matrices”). Library file documentation, including a complete description of datatypes and functions, is available at:

ajmatrices.h/c. Defines the AjPMatrix and AjPMatrixf objects and functions for handling comparison matrices.

There are two datatypes for handling comparison matrix input:

There are two datatypes for handling comparison matrix output:

Typical ACD definitions for comparison matrix input:

#Integer matrix (input)
matrix: matrix
[
    information: "Matrix file"
    protein: "$(acdprotein)"
]

# Floating point matrix (input)
matrixf: matrixf
[
    information: "Matrix file"
    protein: "$(acdprotein)"
]

Typical ACD definitions for comparison matrix output:

# Integer matrix (output)
outmatrix: outmatrix
[
    information: "Matrix file"
    protein: "$(acdprotein)"
]

# Floating point matrix (output):
outmatrixf: outmatrixf
[
    information: "Matrix file"
    protein: "$(acdprotein)"
]

For handling comparison matrices, including input matrices defined in the ACD file, use:

For handling comparison matrix output use:

It is sometimes necessary to convert a sequence into numerical form for convenient processing. The AJAX datatype for this is:

Datatypes and functions for handling comparison matrices via the ACD file are shown below (Table 6.16, “Datatypes and Functions for Comparison Matrix Input and Output”).

Your application code will call embInit to process the ACD file and command line (see Section 6.3, “Handling ACD Files”). All values from the ACD file are read into memory and files are opened as necessary. You have a handle on the files and memory through the ajAcdGet* family of functions which return pointers to appropriate objects.

    AjPMatrix matrix = NULL;

    matrix = ajAcdGetMatrix("matrix");

    AjPMatrixf matrix = NULL;

    matrix = ajAcdGetMatrixf("matrix");

    AjPOutfile outmatrix=NULL;

    outmatrix = ajAcdGetOutmatrix("outmatrix");

    AjPOutfile outmatrixf=NULL;

    outmatrixf = ajAcdGetOutmatrixf("outmatrixf");

    AjPOutfile outmatrix  = NULL;
    AjPOutfile outmatrixf = NULL;

    outmatrix = ajAcdGetOutmatrix("outmatrix");
    outmatrixf = ajAcdGetOutmatrixf("outmatrixf");

    /* Do something with matrices */

    ajOutfileClose(&outmatrix);
    ajOutfileClose(&outmatrixf);

Most elements of a matrix object can be retrieved by calling one of the ajMatrixGet* or ajMatrixfGet* functions:

To return the comparison matrix as an array of integer or floating point arrays call:

AjIntArray*  ajMatrixGetMatrix (const AjPMatrix thys);                                  
AjFloatArray*  ajMatrixfGetMatrix (const AjPMatrixf thys);

Sequence characters are indexed in this array using the internal sequence conversion table in the matrix. AjIntArray and AjFloatArray are defined ajdefine.h as arrays of C-type integer and floating point numbers:

typedef float*  AjFloatArray;
typedef int*  AjIntArray;

To return the label (sequence character or the column name for an asymmetric matrix) for a matrix row or column in position i call:

AjPStr  ajMatrixGetLabelNum (const AjPMatrix thys, ajint i);
AjPStr  ajMatrixfGetLabelNum (const AjPMatrixf thys, ajint i);

To return the sequence character conversion table for a matrix call:

AjPSeqCvt  ajMatrixGetCvt (const AjPMatrix thys);                                       
AjPSeqCvt  ajMatrixfGetCvt (const AjPMatrixf thys);

This table converts any character defined in the matrix to a positive integer, and any other character is converted to zero.

To return the character codes for each offset in the matrix call:

AjPStr  ajMatrixGetCodes (const AjPMatrix thys);
AjPStr  ajMatrixfGetCodes (const AjPMatrixf thys);

To return the name of a matrix object (which typically is the filename from which it was read), call:

const AjPStr  ajMatrixGetName (const AjPMatrix thys);
const AjPStr  ajMatrixfGetName (const AjPMatrixf thys);

To return the comparison matrix size (or the number of columns for an asymmetric matrix) call:

ajuint  ajMatrixGetSize (const AjPMatrix thys);                                         
ajuint  ajMatrixfGetSize (const AjPMatrixf thys);

For an asymmetric matrix the number of rows can be returned by calling:

ajuint  ajMatrixGetRows (const AjPMatrix thys);                                         
ajuint  ajMatrixfGetRows (const AjPMatrixf thys);

To convert a sequence to index numbers using the matrix's internal conversion table call:

AjBool  ajMatrixSeqIndex (const AjPMatrix thys, const AjPSeq seq, AjPStr* numseq);
AjBool  ajMatrixfSeqIndex (const AjPMatrixf thys, const AjPSeq seq, AjPStr* numseq);

Sequence characters not defined in the matrix are converted to zero.

These functions handle sequence conversion objects. The basic constructor ajSeqcvtNewStr uses an array of strings as the column labels. For sequence comparison matrices these strings will be one character each. The other constructors renumbers the codes for the specific expectations of some older legacy code and are not recommended for general use. The most useful functions are those which return the numeric code for a base or residue, and are frequently used to look up a sequence character in a conversion table.

/* constructors with base codes as a string*/
AjPSeqCvt  ajSeqcvtNewStr (const AjPPStr bases, ajint n);
AjPSeqCvt  ajSeqcvtNewC (const char* bases);
AjPSeqCvt  ajSeqcvtNewNumberC (const char* bases);
AjPSeqCvt  ajSeqcvtNewEndC (const char* bases);

/* asymmetrix conversion table constructor */

AjPSeqCvt    ajSeqcvtNewStrAsym (const AjPPStr bases, ajint n, const AjPPStr rbases, ajint rn);

/* destructor */

void         ajSeqcvtDel (AjPSeqCvt* thys);

/* return conversion table length */

ajuint       ajSeqcvtGetLen (const AjPSeqCvt thys);

/* return numeric code for a residue code (matrix column label) */

ajint        ajSeqcvtGetCodeK (const AjPSeqCvt thys, char ch);
ajint        ajSeqcvtGetCodeS (const AjPSeqCvt thys, const AjPStr ch);

/* return numeric code for a column or row in an asymnmetric matrix */

ajint        ajSeqcvtGetCodeAsymS (const AjPSeqCvt cvt, const AjPStr str);
ajint        ajSeqcvtGetCodeAsymrowS (const AjPSeqCvt cvt, const AjPStr str);